@miaguila/ui

Mi Aguila UI Library is the "source of truth" which contains the reusable UI Components of Mi Aguila Web projects. UI library includes a variety of common UI elements to bootstrap experiences and ensure consistent interaction and style as well as accessibility optimizations. These are Angular components.

Usage

1. In order to use this library within any Mi Aguila's Web project, you have to install the respective npm package (in this case ui library), running the following command:

npm install @miaguila/ui --save-dev

2. Include the installed library in shared.modules.ts:

import { UiModule } from '@miaguila/ui';

@NgModule({
  declarations: [
		...
  ],
  imports: [
    // Angular
		...

    // 3rd party
		...

    // Mi Aguila UI
    UiModule
  ],
  exports: [
    // Angular
		...

    // 3rd party
		...

    // Directives
		...

    // Shared components
		...

    // Mi Aguila UI
    UiModule
  ]
})

3. Go to storybook.miaguila.com in order to look for the needed component, click in the Notes tab**,** and copy its markup:

<ma-button [text]="text" [size]="size" [color]="color" [type]="type"></ma-button>

Component prefix

The prefix for a component selector is ma which represents from Mi Aguila:

ma-button
ma-input
ma-badge
...

Why? Prevents element name collisions with components in other apps and with native HTML elements.

Why? Makes it easier to promote and share the component in other apps.

Why? Components are easy to identify in the DOM.

reference: Style 02-07

Add a new Component in the UI Library

1. Run the following command on the root:

ng g component <component-name> --project=ui

2. Add new component in exports array list:

import { NgModule } from '@angular/core';
import { ButtonComponent } from './button/button.component';

import { InputComponent } from './input/input.component';

import { NewComponent } from './new/new.component';

@NgModule({

declarations: [ButtonComponent, InputComponent, BadgeComponent],

imports: [
...
],

/* Added NewComponent in exports array */
exports: [ButtonComponent, InputComponent, NewComponent]

})

export class UiComponentLibraryModule { }

3. Add new component in public_api.ts in order to make it public:

export * from './lib/button/button.component';

export * from './lib/input/input.component';

export * from './lib/new/new.component'; // Added new component

export * from './lib/ui.module';

UI Component File Structure

Use the following structure to organize your UI Components:

// dependencies
import { Component, Input, Output, OnInit, EventEmitter } from '@angular/core';

import { ToastService } from './toast.service';

// local interfaces
enum Size {
  xs = 'xs',
  sm = 'sm',
  md = 'md',
  lg = 'lg',
  xl = 'xl'
}

enum Style {
  flat = 'flat',
  ghost = 'ghost'
}

// component decorator & class definition
@Component({
  selector: 'ma-toast',
  templateUrl: './toast.component.html',
  styleUrls: ['./toast.component.scss']
})
export class ToastComponent implements OnInit {
  // public properties
  message: string;
  title: string;

  // private properties (Use underscore prefix to identify at a glance)
  private _defaults = {
    title: '',
    message: 'May the Force be with you'
  };
  private _toastElement: any;

  // input properties
  @Input() style: Style;
  @Input() size: Size;
  @Input() text: string;

  // output properties
  // name events without the prefix "on".
  @Output() clicked: EventEmitter<any>;

  constructor(private toastService: ToastService) {
    /* 
      Called before any other lifecycle hook. 
      Use it to inject dependencies.
      Reserve the constructor for simple initialization 
      such as wiring constructor parameters to properties. 
      The constructor shouldn't do anything. 
      It certainly shouldn't call a function that makes 
      HTTP requests to a remote server as a real data 
      service would.
    */
    // Init inputs and local properties
    this.style = Style.flat;
    this.size = Size.md;
    this.text = 'Toast';
    this.onClick = new EventEmitter<any>();
  }

  ngOnInit() {
    /*
      Called after the constructor and called after the first ngOnChanges() 
    */
    this.toastElement = document.getElementById('toh-toast');
  }

  // public methods
  activate(message = this.defaults.message, title = this.defaults.title) {
    this.title = title;
    this.message = message;
    this._show();
    this.toastService.save();
  }

  // name your event handler methods with the prefix "on" followed by the event name.
  onClick() {
    this.clicked.emit(true);
  }

  // private methods (Use underscore prefix to identify at a glance)
  private _hide() {
    this.toastElement.style.opacity = 0;
    window.setTimeout(() => this.toastElement.style.zIndex = 0, 400);
  }

  private _show() {
    this.toastElement.style.opacity = 1;
    this.toastElement.style.zIndex = 9999;
    window.setTimeout(() => this._hide(), 2500);
  }
}

Code scaffolding

Run ng generate component component-name --project ui to generate a new component. You can also use ng generate directive|pipe|service|class|guard|interface|enum|module --project ui.

Note: Don't forget to add --project ui or else it will be added to the default project in your angular.json file.

Push and Deploy new features

Whenever someone wants to add a new component in ui library, it's needed to follow the bellow steps:

1. Clone the Github project:

git clone [https://github.com/MiAguila/miaguila-kit.git](https://github.com/MiAguila/miaguila-kit.git)

2. Every library is within the projects folder

3. This project has 4 main branches

master: It's the main branch (it is the Production environment). It's up to date with each library in npm packages repo (https://www.npmjs.com/).

develop: It's the branch where gather all the new features before being approved by the reviewer in order to merge with master branch.

lib-ui: when you want to add a new feature or make a change in the ui library, you always have to create a new branch as a copy of lib-ui.

lib-theme: when you want to add a new feature or make a change in the theme library, you always have to create a new branch as a copy of lib-theme.

4. Create a new branch from the respective parent branch: For example, If you are going to add or change something in ui library, you should create the new branch from lib-ui.

The created branch has to contain the prefix ui, in this way the continuous integration system knows which library should verify.

when you will push your changes, you have to follow the below flow:

(ui)-my-branch → lib-ui → develop → master

• Make your changes in the new branch (e.g. ui-create-toggle-component).
• Pull request new changes to its parent (e.g. in this case it would be lib-ui).
• If everything is Ok (all the test pass, code reviewer approves, etc), make a pull request from lib-ui to develop branch.
• If everything is Ok (all the test pass, code reviewer approves, etc), make a pull request from develop to master branch.
• The continuous integration system is going to take the new changes pushed in the master branch, it will auto-increment version number of each library, publish new changes in npm packages repo and deploy it to the storybook environment.

Running unit tests (ui library)

Run ng test to execute the unit tests via Karma

Running end-to-end tests (ui library)

Run ng e2e to execute the end-to-end tests via Protractor.

References

The Angular Library Series Part 1 - Creating a Library with Angular CLI

The Angular Library Series Part 2 - Building and Packaging

The Angular Library Series Part 3 - Publishing