feat: update forms doc #1694

sdo-1A · 2024-04-22T10:39:54Z

Proposed change

Update documentation on forms

nx-cloud · 2024-04-22T10:40:57Z

☁️ Nx Cloud Report

CI is running/has finished running commands for commit ddba39a. 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.

mrednic-1A · 2024-04-22T14:48:55Z

packages/@o3r/forms/README.md

@@ -12,7 +12,11 @@ This package is an [Otter Framework Module](https://github.com/AmadeusITGroup/ot
 [![Stable Version](https://img.shields.io/npm/v/@o3r/forms?style=for-the-badge)](https://www.npmjs.com/package/@o3r/forms)
 [![Bundle Size](https://img.shields.io/bundlephobia/min/@o3r/forms?color=green&style=for-the-badge)](https://www.npmjs.com/package/@o3r/forms)

-This module provides utilities to enhance Angular form (asynchronous decorator, additional validator, error store...).
+This module provides utilities to enhance the build of Angular reactive forms in the Otter context. These utilities include:


From what I see this entire module is related to guidelines for a product application, with container/presenter structure for components.
I think we should explain this here in the beginning and maybe add another section where to say that for small apps, be-spoke apps (I don;t know how to name them :D) this module does not bring added value on top of angular forms.
Maybe we can have a discussion inside the team to double check if something from this module can be used in any use-case.
Any thoughts @pginoux-1A @kpanot ?

I agree with you for all the complexity brings by container / presenter.
But some features could be interesting even with as small apps
for example if you want to handle the submission at page level and display the error messages outside the form component

Also, we should probably avoid "in the Otter context", from an outside perspective this is really scary. If I don't know what Otter is, I would imagine a big black box with guidelines from an entity I know nothing about.
Unlike Angular, ware not known enough to use this kind of sentence in a public documentation.
I would replace it with the actual context (described by @matthieu-crouzet and @mrednic-1A ) on where our utilities can be useful.

docs/forms/FORM_ERRORS.md

matthieu-crouzet · 2024-04-22T15:11:07Z

docs/forms/FORM_ERRORS.md

-    - __longTranslationKey__ used for a more detailed message on the same error
-    - __translationParams__ translations parameters
-    - __validationError__ original error object
+- `ErrorMessageObject` is associated to an error message on a field. It contains:


Shouldn't this kind of doc be in the tsdoc only ?

It depends, on the usage, it is nice to see how to use this model without going through the code. But maybe it could be more interesting to see how to use it instead of writing a tsdoc.

matthieu-crouzet · 2024-04-22T15:15:50Z

docs/forms/FORM_ERRORS.md


-<a name="customerrors"></a>
+We have to make sure that we provide the `htmlElementId` of the errors in the store that match the __HTML fields__.
+For this, the presenter receives an `id` as input and for each field we are concatenating, the `id` with the `formControlName`.


We anymore generate components with a default id, overridable by input.

Suggested change

For this, the presenter receives an `id` as input and for each field we are concatenating, the `id` with the `formControlName`.

To identify a field, we can generate an `id` in the container instance, provide it through the input mechanism, and concatenate it with the `formControlName`.

maybe we could remove references to the container?

docs/forms/FORM_ERRORS.md

matthieu-crouzet · 2024-04-22T15:36:48Z

docs/forms/FORM_ERRORS.md

-<a name="customerrors"></a>
+We have to make sure that we provide the `htmlElementId` of the errors in the store that match the __HTML fields__.
+For this, the presenter receives an `id` as input and for each field we are concatenating, the `id` with the `formControlName`.
+Since the container sets a __unique id__, we are sure to have unique HTML identifiers for the form fields.


To complement the comment just above

Suggested change

Since the container sets a __unique id__, we are sure to have unique HTML identifiers for the form fields.

Since we will have a __unique id__ by instance of the container, we are sure to have unique HTML identifiers for the form fields.

matthieu-crouzet · 2024-04-22T15:39:07Z

docs/forms/FORM_ERRORS.md

-For the localization of the error messages we keep the same way we have today ([LOCALIZATION](../localization/LOCALIZATION.md)), but we have specific places where to define the default translations of error messages.
-<a name="translationcustomerror"></a>
+For the localization of the error messages, we keep the same way of working as we have today (check out [LOCALIZATION](../localization/LOCALIZATION.md)),
+but we have specific places where to define the default translations of error messages.


Where is this specific places ?
I think the place is the same as all others localization key.
maybe we can remove this sentence.

docs/forms/FORM_ERRORS.md

matthieu-crouzet · 2024-04-22T15:51:25Z

docs/forms/FORM_STRUCTURE.md

+__Presenter class:__
+   * Here we have to create the `formGroup`/`formArray`/`formControl` object.
+   * Provide [NG_VALUE_ACCESSOR](https://angular.io/api/forms/NG_VALUE_ACCESSOR) - used to provide a [ControlValueAccessor](https://angular.io/api/forms/DefaultValueAccessor) for form controls, to write a value and listen to changes on input elements.
+   * Provide [NG_VALIDATORS](https://angular.io/api/forms/NG_VALIDATORS) - this is an [InjectionToken](https://angular.io/api/core/InjectionToken) for registering additional synchronous validators used with forms.
 ```typescript
 // in presenter class
 @Component({


Should we keep an example like that in the doc
or have it in the showcase and add a link to it here

cpaulve-1A · 2024-04-23T07:24:15Z

packages/@o3r/forms/README.md

@@ -12,7 +12,11 @@ This package is an [Otter Framework Module](https://github.com/AmadeusITGroup/ot
 [![Stable Version](https://img.shields.io/npm/v/@o3r/forms?style=for-the-badge)](https://www.npmjs.com/package/@o3r/forms)
 [![Bundle Size](https://img.shields.io/bundlephobia/min/@o3r/forms?color=green&style=for-the-badge)](https://www.npmjs.com/package/@o3r/forms)

-This module provides utilities to enhance Angular form (asynchronous decorator, additional validator, error store...).
+This module provides utilities to enhance the build of Angular reactive forms in the Otter context. These utilities include:


Also, we should probably avoid "in the Otter context", from an outside perspective this is really scary. If I don't know what Otter is, I would imagine a big black box with guidelines from an entity I know nothing about.
Unlike Angular, ware not known enough to use this kind of sentence in a public documentation.
I would replace it with the actual context (described by @matthieu-crouzet and @mrednic-1A ) on where our utilities can be useful.

cpaulve-1A · 2024-04-23T07:25:10Z

packages/@o3r/forms/README.md

+This module provides utilities to enhance the build of Angular reactive forms in the Otter context. These utilities include:
+* An asynchronous decorator (`@AsyncInput`) to ensure subscriptions are handled if the references of the input observables change.
+* Basic and custom validators to validate user input for accuracy and completeness.
+* A dedicated NgRX store for form errors to have the possibility of displaying error messages.


Suggested change

* A dedicated NgRX store for form errors to have the possibility of displaying error messages.

* A dedicated NgRX store for form errors to have the possibility of displaying error messages outside the form component.

Not sure if this is useful to mention...

cpaulve-1A · 2024-04-23T11:50:19Z

docs/forms/FORM_ERRORS.md

 # Form errors

-Handling the form errors in Otter context (container/presenter, localization ...), it's a bit different from creating a form in a component and do all the logic there.
-<a name="store"></a>
+Handling the form errors in the Otter context (container/presenter, localization, etc.) is a bit different from creating a form in a component and doing all the logic there.


Why is the way of handling errors in the Otter context different? And is it really true that this is only for an Otter context? This might be a bit scary when we actually just want to share some guidelines and utilities to help developer solve some architectural challenges?

cpaulve-1A · 2024-04-23T11:52:00Z

docs/forms/FORM_ERRORS.md

- __ElementError__
-This object contains all the errors associated to the html element.
-The identifier __htmlElementId__ can be used as an anchor link to focus on the html element on which the validation has failed
+- The `ElementError` object contains all the errors associated to the HTML element.


Make sure to introduce the ElementError if you remove the code above. If not, please ignore this message :)

cpaulve-1A · 2024-04-23T11:53:52Z

docs/forms/FORM_ERRORS.md

-This object contains all the errors associated to the html element.
-The identifier __htmlElementId__ can be used as an anchor link to focus on the html element on which the validation has failed
+- The `ElementError` object contains all the errors associated to the HTML element.
+The identifier `htmlElementId` can be used as an anchor link to focus on the HTML element where the validation failed.


I guess this is a property from the ElementError interface but this could be stated directly

docs/forms/FORM_ERRORS.md

cpaulve-1A · 2024-04-23T12:05:15Z

docs/forms/FORM_ERRORS.md

-We have to make sure that we are providing the __htmlElementId__ for the errors in the store which is matching the __html field__.
-For this, the presenter is receiving an __id__ as input and for each field we are concatenating the __id__ with the __formControlName__. As the container is setting a __unique id__ we are sure that we have uniques html ids for the form fields.
-The object returned by the __validate__ is the error object which is propagated to the container.
+The presenter has to implement the [Validator](https://angular.io/api/forms/NG_VALIDATORS) or the [AsyncValidator](https://angular.io/api/forms/NG_ASYNC_VALIDATORS) interface


If we want to leave out the presenter/container structure, maybe we should instead refer to the presenter here as the input element, or the ControlValueAccessor?

docs/forms/FORM_ERRORS.md

cpaulve-1A · 2024-04-23T12:50:23Z

docs/forms/FORM_ERRORS.md

-This one is using _customErrors_ key with an array of __ErrorMessageObject__ which has to contain all the custom errors for a form control or group.
+There are two types of validators (see [Form Validation](./FORM_VALIDATION.md)) and therefore two categories of error messages:
+
+- __Custom error__ - set in the container


I think it could be worth to add something about why setting an error in the presenter or in the container.

In the form validation file, the difference between the two validators is explained, should I re explain the difference between the two errors here?

mrednic-1A · 2024-05-06T13:19:41Z

apps/showcase/src/components/showcase/forms/forms-pres.component.ts

+  public translations: FormsPresTranslation;
+
+  /** Observable used to notify the component that a submit has been fired from the page */
+  public submitTrigger$: Observable<boolean>;


This has to be an @input @AsyncInput received from the page component in order to notify this component to trigger a submit. I am assuming here that we have a button on the page component which triggers the submit, not on this component.
With the button on this component we don't need the observables to handle the submit, we call directly submitAction.
But I think we want to showcase the complex example so I would move the button at page level and transform the submitTrigger in an Input.

The button is in this component, and not on the page.

To explain the structure, I have a page which contains the forms component (this current component), which contains two subcomponents (forms-personal-info and forms-emergency-contact) each having a form. The submit button is in the forms component, but if you prefer I can make the structure more complex and move the button to the page.

If the button is in this component, then it would be enough to call 'submitAction' method when clicking on the button, no ? (no need of the observables)

mrednic-1A · 2024-05-06T13:25:45Z

apps/showcase/src/components/showcase/forms/forms-pres.component.ts

+      console.log('FORMS COMPONENT: emergency contact form status', this.emergencyContactFormControl.status);
+      // eslint-disable-next-line no-console
+      console.log('FORMS COMPONENT: submit logic here', this.personalInfoFormControl.value, this.emergencyContactFormControl.value);
+    }


Could you create an issue to track the errors case with the example of the store usage ?

Would you like me to update the PR and add the store to track the errors? Or would you prefer for me to create an issue?

another issue would be cleaner imo.

cpaulve-1A · 2024-05-30T13:56:43Z

apps/showcase/src/app/forms/forms.component.ts

+  private readonly inPageNavLinkDirectives!: QueryList<InPageNavLink>;
+  public links$ = this.inPageNavPresService.links$;
+
+  constructor(private readonly inPageNavPresService: InPageNavPresService) {}


Suggested change

constructor(private readonly inPageNavPresService: InPageNavPresService) {}

private readonly inPageNavPresService = inject(InPageNavPresService);

cpaulve-1A · 2024-05-30T14:01:33Z

apps/showcase/src/components/showcase/forms/forms-pres.component.ts

+  private readonly forbiddenName = 'Test';
+
+  constructor() {
+    this.translations = translations;


You don't need to do these in the constructor - you could directly set the value when declaring the properties

cpaulve-1A · 2024-05-30T14:06:28Z

apps/showcase/src/components/showcase/forms/forms-pres.component.ts

+    if (isValid) {
+      this.submittedFormValue = JSON.stringify(this.personalInfoFormControl.value) + '\n' + JSON.stringify(this.emergencyContactFormControl.value);
+      // eslint-disable-next-line no-console
+      console.log('FORMS COMPONENT: personal info form status', this.personalInfoFormControl.status);


You should probably leave the submitForm logic to each form and just call submitPersonalInfoForm and the other one.
This would highlight that you do not need to duplicate each blocks submit action logic but let them handle it.

I would have prefer two different component to really highlight each component is the owner of its business logic but we can keep it this way if you think that would be overkill

cpaulve-1A · 2024-05-30T14:10:49Z

apps/showcase/src/components/showcase/forms/forms-pres.component.ts

+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush
+})
+export class FormsPresComponent {


Maybe you can rename it because it does not fit the Presenter pattern (too much logic)

cpaulve-1A · 2024-05-30T14:12:34Z

...e/src/components/utilities/forms-emergency-contact/forms-emergency-contact-pres.component.ts

+  constructor(fb: FormBuilder, protected changeDetector: ChangeDetectorRef) {
+    this.translations = translations;


you could use injectors

cpaulve-1A · 2024-05-30T14:38:57Z

docs/forms/README.md

+> The first subcomponent has a form for the user to fill out their personal information and the second subcomponent has a form for the user to fill out
+> information about their emergency contact. In this example, the two subcomponents correspond to input components.
+>
+> You can find the implementation of this forms example [here](../../apps/showcase/src/components/showcase/forms).


Suggested change

> You can find the implementation of this forms example [here](../../apps/showcase/src/components/showcase/forms).

> You can find the implementation of this forms example [in the showcase code source](../../apps/showcase/src/components/showcase/forms).

Also do we support relative link to the application (the documentation is published on a separated url)

cpaulve-1A · 2024-05-30T14:43:48Z

docs/forms/FORM_STRUCTURE.md

+* The __form creation__ (it can be a [__FormGroup__](https://angular.io/api/forms/FormGroup) or [__FormArray__](https://angular.io/api/forms/FormArray) 
+  or [__FormControl__](https://angular.io/api/forms/FormControl)) should be done __in the input component__ because:
+   * It is up to the input component to decide how the data will be displayed/computed. For example, a date can be displayed in an input field
+    ([FormControl](https://angular.io/api/forms/FormControl)) in one input component, or in a [FormGroup](https://angular.io/api/forms/FormGroup) containing


Suggested change

([FormControl](https://angular.io/api/forms/FormControl)) in one input component, or in a [FormGroup](https://angular.io/api/forms/FormGroup) containing

([FormControl](https://angular.io/api/forms/FormControl)) in one input component or in a [FormGroup](https://angular.io/api/forms/FormGroup) containing

cpaulve-1A · 2024-05-30T14:46:51Z

docs/forms/FORM_STRUCTURE.md

-Container/presenter architecture was put in place to ensure the best re-usability/sharing
-<a name="form-creation"></a>
-### Form creation in container or in presenter?
+This documentation will help you with some best practices to use when building Angular reactive forms components that have a parent/input component structure (such as container/presenter).


Maybe mention this is in fact only an implementation of the ControlValueAccessor pattern but we chose to guide them with this example

(and that we cover as well the errors but I guess this is in another section :) )

cpaulve-1A · 2024-05-30T14:58:08Z

docs/forms/FORM_STRUCTURE.md

-   * we will not use the formGroup / formArray / formControl object as a two-way data binding object between the container and the presenter.
-* The __container__ needs only the value and in some specific cases the errors propagated from the presenter. If needed it can set the default value
+## Parent/input component and reactive forms
+A parent/input component (such as [container/presenter](../components/COMPONENT_STRUCTURE.md)) architecture was put in place to ensure the best reusability and sharing of components.


This is a bit repetitive with the previous paragraph

cpaulve-1A · 2024-05-30T15:00:24Z

docs/forms/FORM_ERRORS.md

-The store is provided in __@o3r/forms__ package. See [Form Error Store](https://github.com/AmadeusITGroup/otter/blob/main/packages/@o3r/forms/src/stores/form-error-messages/form-error-messages.state.ts) for more details and state object model.
-<a name="errormodel"></a>
+To have the possibility of displaying inline error messages in the form and also in error panels (on the top of the page, above the submit button, etc.),
+the best option is to have a dedicated NgRX store for the form errors. This way we can listen to the store state and display the errors anywhere in the page.


"The best" is maybe a bit too much ;)

cpaulve-1A · 2024-05-30T15:02:17Z

docs/forms/FORM_ERRORS.md

-<a name="createerror"></a>
+We have to make sure that we provide the `htmlElementId` of the errors in the store that match the __HTML fields__.
+To identify a field, we can generate an `id` in the parent component instance, provide it through the input mechanism, and concatenate it with the `formControlName`.
+Since we will have a __unique id__ by instance of the parent component, we are sure to have unique HTML identifiers for the form fields.


A link with the showcase code could be nice to include as examples

cpaulve-1A · 2024-05-30T15:05:21Z

docs/forms/FORM_ERRORS.md


- one for __custom errors__ - set on the container
- one for __primitive errors__ - computed in the presenter.
+- __Custom error__ - set in the parent component


Suggested change

- __Custom error__ - set in the parent component

- __Custom error__ - defined in the parent component as it holds the business logic

sdo-1A requested a review from a team as a code owner April 22, 2024 10:39

github-actions bot added documentation Improvements or additions to documentation enhancement New feature or request project:@o3r/forms labels Apr 22, 2024

mrednic-1A reviewed Apr 22, 2024

View reviewed changes

sdo-1A force-pushed the doc/forms branch from bd61c7b to 6769a51 Compare April 22, 2024 15:05

matthieu-crouzet reviewed Apr 22, 2024

View reviewed changes