BRIE
About
Brie is a library and collection of UI components meant to be used within all the brXM frontend applications, with the ultimate goal of building a consistent user experience.
See more at BRIE Introduction storybook for general information.
Core contributors
Working with brie in your local app
When working on an application you will likely find yourself in the situation where you need to also make changes to a brie component. There are two ways to test local changes made to the library.
The simplest option is make your changes in the component and test them via the existing Storybook integration. This is best suited for testing the component API and other basic interactions.
Another way to test changes is to test the component directly within the context where it is being used, for example as part of one of the existing FE applications. This is possible out of the box since the brie project folder is mapped to the dependency within the FE application. This is configured via lerna or yalc.
Component development practices
Please read this section before contributing to the library. Any addition to the library must adhere to these practices for consistency, readability and maintainability reasons.
Development practices
// TO BE ADDED
Testing
When adding changes for any component part of the library it is mandatory to have them covered by tests. These tests need to be meaningful and developed with extensive coverage in mind. By their nature components will be used in a wide variety of scenarios and so extensive coverage is crucial in order to avoid unpredictable results.
As a rule of thumb, use the followings testing practices:
- Snapshot testing
- Prefer snapshot testing over unit testing because it allows you to reduce the time spent writing often large amounts of testing boilerplate code
- Unit testing
- No integration testing
- Do not test components interacting with each other, this should be tested within the application that implements the interaction
What should be covered by tests?
- Snapshots of the final rendered component in the various meaningful states
- Component class methods
- If a method has a single branch then they are usually already covered by snapshot tests
- Asynchronous events
- click, hover, blur, etc.
- promises
Versioning strategy
// TO BE ADDED
Form validation (validate-on-submit)
BRIE provides optional helpers for the enable-on-change + validate-on-submit pattern. All APIs are opt-in; existing consumers are unaffected.
Template form (existing pattern)
<form [formGroup]="group" brieShowErrorsOnSubmit [brieFocusFirstError]="true" (ngSubmit)="onSubmit()">
<brie-form [group]="group" [dataSource]="fields"></brie-form>
<button mat-flat-button type="submit">Save</button>
</form>
Programmatic validation
Inject BrieFormValidationService from @bloomreach/brie/form:
save(): void {
const result = this.validationService.showValidationErrors(this.form, {
focusFirstError: true,
focusRoot: this.formElement.nativeElement,
});
if (!result.valid) {
return;
}
// proceed with save...
}
Button opt-in (brie-button-group / brie-heading)
{
id: 'button-save',
text: 'Save',
isDisabled: () => !this.form?.dirty,
validateBeforeAction: true,
validateForm: () => this.form,
validateFormOptions: { focusFirstError: true, focusRoot: this.formElement.nativeElement },
action: () => this.save(),
}
Legacy pattern (isDisabled: () => this.form.invalid without validateBeforeAction) continues to work unchanged.
See Storybook stories LegacyDisabledUntilValid and ValidateBeforeAction under Components/Button Group.
Copyright 2022 Bloomreach. All rights reserved.