umbrella-library v1.3.2

Umbrella Library

This library provides reusable components for use inside the SRS Umbrella UI, a complex customer-facing frontend appllication that employs module federation and microfrontends.

This library was originally generated with Angular CLI version 12.2.0.

TOC

Installation

To install and run this application locally, you need to have NodeJS installed at a version of 10.0 or greater.

To complete installation and run the app locally, please follow these instructions.

Directory Structure

/lib - This is where the exportable library files and features are.

• /lib/public-modules - Place all components and services that will be made publicly available from this library here
• /lib/public-api.ts - List all exported components and services here.

Major Features

Data Table

This custom exported component can handle -- and should be used -- for most of the many data tables used in the Umbrella UI.

Below is a list of the @input parameters the component can handle for customization and configuration:

• tableId: string - A unique ID for the data-table
• columns: any[] - An array of columns, each of type shared/types/data-table-column.type, specifying the columns of data to display
• service: any - The service that the data-table uses to fetch and update data from the API
• dataSource: any - The datasource file that enables the Material table to function
• dataSet: any[] - Customize via filters what data is fetched from the API and appears in the table.
• dropdownOptions: any[] - An object configuring the drop-down options available for each row in the table when clicking the meatballs icon
• search: boolean - Whether or not the table should offer a search bar
• showDownloadButton: boolean - Show/Hide download csv button
• downloadFileName: string - Downloaded csv file name
• searchFields: string - A comma-delimited list of the searchable fields
• filter: boolean - Whether or not the table should offer filtering UI
• filters: any - An object configuring which filters are available to the user, and whether they are preselected or not.
• lookupTables: any - Tables that can be used to display data rather than simply IDs that are part of a row of the data
• actionButton: boolean - Whether or not the table should offer action buttons, such as Delete or Edit, atop the table
• buttonActions: any - An object configuring the actions available when actionButtons is set to true
• checkboxColumn: boolean - Whether or not the table should offer an ID column of checkboxes, enabling multi-select of the rows of the table
• statusColumn: boolean - Whether or not to show a status column

• width: string - Whether the table should be narrow or not. Use 'narrow' if so.

  As for display, all data is displayed as standard Ant table data unless a format field is present when the column is defined. If a format field is defined, these are the options:

• date - The data will be displayed in the table as a date.

• twoFields - Two fields will be concatenated as strings. Useful for a full name field, for instance.
• boolean - A boolean data field will be displayed with one of two defined strings, depending on whether the data is true or false.
• label - Data can be displayed as colored labels. Pass into the format object format.type = 'label' and a format.labels object with key(s) that are the value(s) you want to display labels for, and the value(s) are mini-objects containing labelText and labelColor for each value. The colors currently available are green, red and gray.
• lookupTable - A data table can be used to display text depending on the data for each row. This data table can be loaded asynchronously in the makeLookupTables() component function.

• image - An image can be displayed, as defined in the format.src field.

  Header

  This custom component displays the header for the MFE, including the name of MFE and any buttons on the top left.

  The @input parameters for this component:

• title string - The title of the entire application.

• subTitle: string - A secondary title string.
• tags: HeaderTag[] - An array of tags for the header using HeaderTag type
• primaryButton: ActionButton - The primary button on the upper right.
• secondaryButtons: ActionButton[] - An array of ActionButton that will appear to the left of the primary button.
• ellipsisDropdownItems: MenuDropdownItem[] - Dropdown options.
• breadcrumbItems: HeaderBreadcrumb[] - Navigation breadcrumb links.

• navRoutes: HeaderNavRoute[].

  Footer

• primaryButton: ActionButton - An optional primary button in the footer.

• secondaryButtons: ActionButton[] - An array of ActionButton that will appear to the left of the primary button.

  Error Interceptor

  The Umbrella Error Interceptor handles automatic logout for expired tokens. It should be added to all MFEs.

  To add it to a MFE, simply import it in whatever module imports the HttpClientModule (probably the MFE's Shared or App module).

1. Add HTTP_INTERCEPTORS to your import from Angular's http library
2. Add UmbrellaErrorInterceptor to your Umbrella Library import

3. In the Module configuration, use a providers property and add the Umbrella Error Interceptor

   import { HttpClientModule, HTTP_INTERCEPTORS } from '@angular/common/http';

import { UmbrellaHeaderModule, UmbrellaFooterModule, UmbrellaDataTableModule, UmbrellaErrorInterceptor } from 'umbrella-library';

@NgModule({ providers: { provide: HTTP_INTERCEPTORS, useClass: UmbrellaErrorInterceptor, multi: true, } , imports: [ ...

*Note: If your MFE has its own Error Interceptor, you can simply add it as another stanza inside the `providers` array. Ensure both Interceptors stanzas have the `multi:true` property.*


# Extending the Application

## Contributing

To add new features or new components to this library:
1. Create a new directory in the `public-modules` directory to host your new feature. 
1. Create your components or services there with Code Scaffolding and `ng generate` commands, as [specified below](#code-scaffolding).
1. Name your exported class the way you would like it be imported into our Umbrella microfrontends.
1. Write your code to customize your component.
1. Add a stanza in the `/public-api.ts` file to ensure the library will export your new feature.
1. Use the [directions below](#publishing-the-library) and publish a new version to npm:
  * Publish a minor version if the changes are not going to break or require changes in any other components.
  * Publish as a new major version if there are breaking changes.


Whether you're adding new features or simply fixing bugs in this shared library, always:
* Write unit tests for your components.
* Use Prettier and utilize formatting and linting to add code that is compliant with the [standards listed below](#code-formatting).
* Follow the Git branching strategy [below](#git-branching-model) to create your branches.
* Write your Pull Request as specified [below](#pull-requests).
* Update this README if and when necessary! 
* That's it! 🎉




## Code Scaffolding

Run `ng generate component component-name --project umbrella-library` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module --project umbrella-library`.
-> Note: Don't forget to add `--project umbrella-library` or else it will be added to the default project in your `angular.json` file.


## Code Formatting

This application requires well-formatted code. It is recommended you set up automated code formatting. The easiest way to do this is to simply configure your IDE to format files on every save as follows:

### Automated Formatting

Configure your IDE to run the `format:all` command upon save. With VSCode, this can be done by installing a plugin such as [RunOnSave](https://marketplace.visualstudio.com/items?itemName=emeraldwalk.RunOnSave). If you do install RunOnSave, simply add this configuration to your VSCode's `settings.json`:

"emeraldwalk.runonsave": { "commands": { "match": ".*", "cmd": "npm run format:all" } }

### Manual Formatting

If you don't choose to set up auto-formatting, you can also manually format your code with :

**- Prettier (TS, CSS)**. We use [Prettier](https://prettier.io/) to format all files except for HTML (see below). Manually call `npm run format:prettier` to format all TS, CSS, and config files inside the `src` directory. This command is an alias for `npx prettier --write src`, which you can also use if you prefer not to use the alias, and you can replace the `src` with a single file or directory, and the relevant file(s) will be formatted automatically according to our current prettier standards. You can replace the `--write` with `--check` to simply check formatting without making changes. There's also

**- JSBeautify (HTML)**. We use [JSBeautify](https://beautifier.io/) to format HTML files. You can use `npm run format:html` to format all HTML files in the repository. You can also use `npm run format:html-file [FILE]` to format a single file.

**_Run All Formatting_**. Use `npm run format:all` and all TS, CSS, and HTML files inside the `src` directory will be formatted automatically for you. This is command you should automate or run prior to creating your Pull Requests.


### Other Commands

In addition, the following npm script commands are available when working on this application:

**- Code Formatting (HTML)**. Use `npm run format -- '[FILE]'` on an HTML template file named *FILE*, and the file will be formatted automatically according to our current linting standards. You can also run `npm run format: all` to reformat all html files of the application at once.

**- Code Linting (TS)**. Use `npm run lint --files '[FILE]'` on a TS script file named *FILE* to see lint errors for that file (but make no changes to it). Append `--fix` to this command to fix *some* of the issues automatically for you.


## Git Branching Model

We use git to manage all of our development flow.
*Please create branches and pull requests properly.* Read our [Git Branching Model](https://greenlots.atlassian.net/wiki/spaces/DEV/pages/1787396374/Driver+Portal+-+Git+Flow+Build+Processes) to accomplish this. (That document is specific to the Driver Portal, but the model is the same for this application).


## Code Comments

### Explanations
Generally code should be clear and not complex so that inline documentation and explanation is not necessary. However, whenever the code is complex or uses a solution or algorithm that will not be readily apparent to another engineer who might review or extend the code, always add comments explaining the solution or algorithm used. `/* */` comment notation should be used for these explanatory comments.

### Unused code
Code that is currently unneeded should generally be removed from the repository. There is no need to keep unused code as the git history will keep it. However, during initial buildout of features or when the API integration is unstable or not yet used, there will be times to **temporarily** commment out code. `//` comment notation should be used. This way code comments is immediately differentiated from unneeded code.

### TODOs
Tasks that should be completed soon and that are not captured in JIRA tickets can be noted with JSDoc's `/* @TODO */` notation. This way a quick search on the @TODO will bring up all the tasks flagged in the code. Also if we utilize JSDoc in the future, the @TODO notation will be helpful.



## Pull Requests

An optimal PR for our git history explains all of the changes that it makes to the repository with a title and description that is easy to read and to
understand, and (if necessary) to revert.

### PR Title

The title of the PR should be a very brief imperative-voice description of what the PR does,
prefixed by the JIRA story abbreviation it addresses. (If there is no JIRA ticket,
use the component that the pull request affects or "[MAINT]" if the PR addresses repository
maintenance):

{{ [JIRA-XXX] }} - {{ Brief summary of what PR does }}

eg:

    [FS-326] - Fix settings menu

If a pull request is **not** to be considered for merging (yet), please prefix the PR title with [WIP] or [DO NOT MERGE] to indicate the code isn't intended to be merged.

### PR Body

While this isn't required, the body of the pull request ideally helps the next engineer review the code by following the _Problem/Solution/Result_ pattern. Each section
should contain a description or list of items. The _Solution_ section should describe what each change does, together with any justifications, reasoning, or concerns. Include
a link to the JIRA ticket when possible in the _Problem_ section.

eg:

PROBLEM
- Description (eg: Can’t view the menu)
- [JIRA ticket link]

SOLUTION
- What you did, what files were edited, why
- (eg: Fixed menu visibility)

RESULT
- User experience change
- (eg: Menu now appears on click)
- Any changes engineers will experience
- If changes to UI are substantial or important, include screenshot of the app showing changes to the UI.

# Publishing the Library
When you have finished making your changes, publish a version to npm. We use the Angular CLI and the npm package managerto build and publish the library as an npm package.

Make all of your changes inside the `/projects/umbrella-library/src` directory.

Then, to build and publish to npm, step back out to the `projects` directory and build and publish:

ng build umbrella-library cd ../dist/umbrella-library npm version bump to new version npm publish

*Note: You may need to use the public access flag when publishing: `npm publish --access=public`*

From [Angular documentation](https://angular.io/guide/creating-libraries#publishing-your-library): You should always build libraries for distribution using the production configuration. This ensures that generated output uses the appropriate optimizations and the correct package format for npm.

# Monitoring

Information on site monitoring coming soon:
- Health Check
- NodePing
- New Relic


# Further help

To get more help on the Angular CLI use `ng help` or review the [Angular CLI README](https://github.com/angular/angular-cli/blob/master/README.md).