CONTRIBUTING.md

Contributing

We'd love for you to contribute to our source code and to make Momentum UI Angular even better than it is today! Below are the guidelines to follow.

Table of Contents

• Questions, Issues or Ideas
  • Issues
  • Features
• Requirements
• Development Environment
• Adding a new component
• Running the project locally
• Testing
• Code Guidelines
• Commit Guidelines
• Submitting a Code Review

Running the project locally

• Run the start script which will build and watch the library, then serve it at localhost:4300
  • yarn start:angular from the root (momentum-ui) directory
  • yarn start from the angular (momentum-ui/angular) directory
• You can access the playground localhost:4300/playground

Adding a new component

1. cd into the angular directory: cd angular/

2. Use npm scripts to create your Module and Component (create module before component). Replace <component-name> with the kebab-cased name of the new component.

   • Create Component Module: yarn gen:m <component-name>
   • Create Component: yarn gen:c <component-name>

3. Add index.ts barrel file and export the module and component by adding the following code:

   export * from './<component-name>.module';
   export * from './<component-name>.component';

4. Add the new component to src/lib/public_api.ts in alphabetical order.

5. Add a tests directory and move the <component-name>.spec.ts file into it.

   • update the import path in the spec file on line 3 from: './<component-name>.component'; to '../<component-name>.component';

6. Add your examples using the following scripts (create module before component). Replace <component-name> with the kebab-cased name of the new component.

   • Create Samples Module:

   yarn gen:m --flat=true -m examples <component-name>/examples/<component-name>-examples

   • Create Samples Component:

   yarn gen:c --flat=true --prefix=example --skipTests=true -m <component-name>/examples/<component-name>-examples <component-name>/examples/<component-name>-default

7. Add CUSTOM_ELEMENTS_SCHEMA to both modules (component and examples)

   • add CUSTOM_ELEMENTS_SCHEMA to the import on line 1: import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
   • add schemas: [ CUSTOM_ELEMENTS_SCHEMA ] after the exports array.

8. Add examples/index.ts barrel file and export the examples module and component by adding the following code:

   export * from './<component-name>-examples.module';
   export * from './<component-name>-default.component';

9. Add the component's examples module to the exports in the library examples module

   • open src/lib/examples.module.ts
   • the component's examples module will already be decared in the "imports" array. Copy it down to the "exports" array and save.

10. Start the app and the new component will now be availble in the Playground.

Your components directory should look like this:

└── lib
    └── sample                                    # component directory
        ├── sample.component.ts                   # component file
        ├── sample.module.ts                      # module file
        ├── index.ts                              # barrel file
        ├── examples                              # examples directory
        |   ├── sample-default.component.ts       # default example component
        |   ├── sample-examples.module.ts         # examples module
        |   └── index.ts                          # examples barrel file
        └── tests                                 # tests directory
            ├── sample.component.spec.ts          # component unit test
            └── __snapshots__                     # snapshots directory (will be generated Jest)
                └── sample.component.spec.ts.snap # snapshots file (will be generated by Jest)

**You can also reference the sample component at src/lib/sample/

Testing

• In the <component-name>/tests/ directory, ensure that you add tests to cover all of the component/directive/service code.
• Run the test and ensure that all tests are passing by running:
  • yarn test from the angular (momentum-ui/angular) directory
  • yarn test:angular from the root (momentum-ui) directory

Coding Guidelines

Angular TypeScript

We follow the angular Style Guide

Patterns for updating classNames on host elements

Base classNames and boolean classNames should be added using @Inputs and the host: property

  host: {
    class: 'md-badge',
    '[class.md-badge--round]': 'rounded',
  }

  @Input() public rounded: boolean = false;

Dynamic classNames that need use the prop as part of the className, should use a setter accessor to add and remove the classNames based on the @Input

  private _color: string = null;
  @Input()
  set color(color: string) {
    console.log('setting color');
    if (this._color) {
      this.elementRef.nativeElement.classList.remove(`md-badge--${this._color}`);
    }
    this.elementRef.nativeElement.classList.add(`md-badge--${color}`);
    this._color = color;
  }

License

By contributing your code to the @momentum-ui/angular GitHub repository, you agree to license your contribution under the MIT license.