@moxa/ui-pro

F2E Pro UI Library

An UI library base on Angular Material for Moxa products.

Documentation

To be continue... (To be come out with Storybook)

Installation

At first, you have to install the Angular Material and set it up. How to install Angular Material.

Then install UI library:

$ npm install @moxa/ui-pro

Usage

Import the modules you're going to use, such as anchor, table...

You might also need to import some dependence modules, like BrowserAnimationsModule, MaterialsModule..., when you're using those modules we provided.

import { MxAnchorModule } from '@moxa/ui-pro/mx-anchor';
@NgModule({
  ...
  imports: [
    CommonModule,
    BrowserModule,
    BrowserAnimationsModule,
    MaterialsModule,
    MxAnchorModule,
  ],
  ...
})
export class AppModule {}

Import Angular Material Modules

Though our ui libraries already update Angular Material package to v15, we still not follow up our design to Material 3. Therefore, we have to import legacy modules from @angular/material temporarily before we follow it up. What shoud I use legacy modules?

import { NgModule } from '@angular/core';
import { MatLegacyButtonModule as MatButtonModule } from '@angular/material/legacy-button';
import { MatLegacyCheckboxModule as MatCheckboxModule } from '@angular/material/legacy-checkbox';
...

@NgModule({
  exports: [
    MatButtonModule,
    MatCheckboxModule,
    ...
  ]
})
export class AppModule {}

Theming

Though our ui libraries already update Angular Material package to v15, we still not follow up our design to Material 3. Therefore, we have to use legacy api from @angular/material temporarily before we follow it up.

There are few things need to add in yours app's global style, like styles.scss, for theming components:

1. include mat.core()
2. define material palette
3. define material light and dark theme
4. include mat.all-component-themes()
5. include customize themingAllcomponents()

@use '@angular/material' as mat;
@use '@moxa/ui-pro' as *; // including base, components, layout styles forwarding
@use '@moxa/ui-pro/theming' as mxTheming;

// @include mat.core();
@include mat.all-legacy-component-typographies();
@include mat.legacy-core();

// UI Library light theme
$mx-app-primary: mat.define-palette($mx-primary, 800);
$mx-app-accent: mat.define-palette($mx-accent, 800);
$mx-app-warn: mat.define-palette($mx-warn, 900);
$mx-app-theme: mat.define-light-theme(
  (
    color: (
      primary: $mx-app-primary,
      accent: $mx-app-accent,
      warn: $mx-app-warn
    )
  )
);

$mx-app-dark-primary: mat.define-palette($mx-primary, 400);
// UI Library dark theme
$mx-app-dark-theme: mat.define-dark-theme(
  (
    color: (
      primary: $mx-app-dark-primary,
      accent: $mx-app-accent,
      warn: $mx-app-warn
    )
  )
);

// @include mat.all-component-themes($mx-app-theme);
@include mat.all-legacy-component-themes($mx-app-theme);
@include mxTheming.themingAllComponents($mx-app-theme);
.mx-dark-theme {
  // @include mat.all-component-themes($mx-app-dark-theme);
  @include mat.all-legacy-component-themes($mx-app-dark-theme);
  @include mxTheming.themingAllComponents($mx-app-dark-theme);
}

Icons

In order to keep the consistency of icon system, we highly recommand to download the icons from Material Icons. We also provided a SVG icons' spritesheet which incoluding the icons commonly used in each apps from Material Icons and the custom icons designed by designer.

There are few steps to use the icons-sprite.svg (which we provide in /assets folder in library package) in your apps:

1. Glob icons-sprite.svg from library's assets forlder, to do that please add the assets config in your project.json

"assets": [
  ...,
  {
    "glob": "icons-sprite.svg",
    "input": "node_modules/@moxa/ui-pro/assets",
    "output": "assets/"
  }
]

2. Make a service for registry SVG into material icon ( here for more details ), like the example below

@Injectable({
  providedIn: 'root'
})
export class IconRegistryService {
  constructor(private matIconRegistry: MatIconRegistry, private domSanitizer: DomSanitizer) {}

  initData() {
    const basePath = window.parent.location.pathname === '/' ? '/assets/' : `${window.parent.location.pathname}assets/`;

    this.matIconRegistry.addSvgIconSetInNamespace(
      'icon',
      this.domSanitizer.bypassSecurityTrustResourceUrl(basePath + 'icons-sprite.svg')
    );
  }
}

3. Invoke the service you just made in last step in app.module to get ready the icons-sprite.svg when app initialization.

 providers: [
    {
      provide: APP_INITIALIZER,
      useFactory: (iconRegistryService: IconRegistryService) => () => iconRegistryService.initData(),
      deps: [IconRegistryService],
      multi: true
    }
  ],

4. Use mat-icon like this ( What icons we provided? ) :

<mat-icon svgIcon="icon:verified_user"></mat-icon>