npm package: @moxa/ui-pro
Description: An UI library base on Angular Material for Moxa products.
Latest version: 1.3.9

# F2E Pro UI Library

An UI library base on Angular Material for Moxa products.

## Documentation

To be continue... (To be come out with [Storybook](https://storybook.js.org/))

## Installation

At first, you have to install the Angular Material and set it up. [How to install Angular Material.](https://material.angular.io/guide/getting-started)

Then install UI library:

```bash
$ 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.

```typescript
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?](https://material.angular.io/guide/mdc-migration)

```typescript
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()

```scss
@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](https://fonts.google.com/icons?icon.style=Filled&icon.set=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`

```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](https://material.angular.io/components/icon/overview#svg-icons) )_, like the example below

```TypeScript
@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.

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

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

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