Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

feat: update forms doc #1694

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat: update forms doc #1694

wants to merge 1 commit into from
+1,887 −1,356

Conversation

sdo-1A
Copy link
Contributor

@sdo-1A sdo-1A commented Apr 22, 2024

Proposed change

Update documentation on forms

@sdo-1A sdo-1A requested a review from a team as a code owner April 22, 2024 10:39
@nx-cloud Nx Cloud
Copy link

nx-cloud bot commented Apr 22, 2024 •
edited
Loading

View your CI Pipeline Execution ↗ for commit 06a74e2.

Command Status Duration Result
nx run-many --target=test-int ✅ Succeeded 3s View ↗
nx run-many --target=build --projects=eslint-pl... ✅ Succeeded 1s View ↗
nx run-many --target=test-e2e ✅ Succeeded 2m 30s View ↗
nx run-many --target=publish --nx-bail --userco... ✅ Succeeded 31s View ↗
nx run-many --target=prepare-publish --exclude-... ✅ Succeeded 7s View ↗
nx affected --target=test --collectCoverage --c... ✅ Succeeded 1m 19s View ↗
nx run ama-sdk-schematics:build-swagger ✅ Succeeded 9s View ↗
nx run-many --target=documentation ✅ Succeeded 1m 21s View ↗
Additional runs (3) ✅ Succeeded ... View ↗

☁️ Nx Cloud last updated this comment at 2025-03-25 10:32:01 UTC

@github-actions github-actions bot added documentation Improvements or additions to documentation enhancement New feature or request project:@o3r/forms labels Apr 22, 2024
mrednic-1A
mrednic-1A reviewed Apr 22, 2024
View reviewed changes
packages/@o3r/forms/README.md Outdated
@@ -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:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 ?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

matthieu-crouzet
matthieu-crouzet reviewed Apr 22, 2024
View reviewed changes
docs/forms/FORM_ERRORS.md Outdated
- __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:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
matthieu-crouzet reviewed Apr 22, 2024
View reviewed changes
docs/forms/FORM_STRUCTURE.md Outdated
__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({
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
cpaulve-1A reviewed Apr 23, 2024
View reviewed changes
packages/@o3r/forms/README.md Outdated
@@ -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:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

packages/@o3r/forms/README.md Outdated
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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure if this is useful to mention...

cpaulve-1A
cpaulve-1A reviewed May 30, 2024
View reviewed changes
@sdo-1A sdo-1A force-pushed the doc/forms branch 2 times, most recently from 2bef32d to 2332915 Compare May 31, 2024 14:27
cpaulve-1A
cpaulve-1A previously approved these changes Jun 5, 2024
View reviewed changes
@sdo-1A sdo-1A force-pushed the doc/forms branch 3 times, most recently from 278675b to 1381aea Compare March 21, 2025 16:31
@codecov Codecov
Copy link

codecov bot commented Mar 21, 2025 •
edited
Loading

Codecov Report

Attention: Patch coverage is 73.83966% with 62 lines in your changes missing coverage. Please review.

Project coverage is 67.66%. Comparing base (834a3ba) to head (06a74e2).
Report is 25 commits behind head on main.

✅ All tests successful. No failed tests found.

Files with missing lines Patch % Lines
...ts/showcase/forms-parent/forms-parent.component.ts 55.55% 24 Missing ⚠️
...ersonal-info/forms-personal-info-pres.component.ts 76.62% 15 Missing and 3 partials ⚠️
...-contact/forms-emergency-contact-pres.component.ts 76.47% 14 Missing and 2 partials ⚠️
...s/showcase/forms-parent/forms-parent.validators.ts 69.23% 3 Missing and 1 partial ⚠️

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@github-actions GitHub Actions
Copy link

doc/forms-update-e2e-screenshots with the updated screenshots has been created!
e7326b9 can be cherry-picked in your branch.

@sdo-1A sdo-1A force-pushed the doc/forms branch 2 times, most recently from 6696f9d to 4400b70 Compare March 24, 2025 17:18
fpaul-1A
fpaul-1A reviewed Mar 25, 2025
View reviewed changes
@sdo-1A
feat: update forms doc
Loading
Loading status checks…
06a74e2
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@matthieu-crouzet matthieu-crouzet

@mrednic-1A mrednic-1A

@fpaul-1A fpaul-1A

@cpaulve-1A cpaulve-1A

At least 2 approving reviews are required to merge this pull request.

Assignees
No one assigned
Labels
documentation Improvements or additions to documentation enhancement New feature or request project:@o3r/forms project:@o3r/showcase
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

None yet
5 participants
@sdo-1A @matthieu-crouzet @mrednic-1A @fpaul-1A @cpaulve-1A