npm package: @smallpearl/ngx-helper
Description: `WARNING: THIS LIBRARY IS UNDER ACTIVE DEVELOPMENT. EXPECT BREAKING CHANGES BETWEEN RELEASES. USE IT AT YOUR OWN RISK.`
Latest version: 21.0.4

# ngx-helper

`WARNING: THIS LIBRARY IS UNDER ACTIVE DEVELOPMENT. EXPECT BREAKING CHANGES BETWEEN RELEASES. USE IT AT YOUR OWN RISK.`

This is a library of angular components and other utility code that are not part of the standard angular/material library. Some components are composite components in that they combile multiple standard material library widgets for a common use case scenario.

This is meant to be a private library for my own experiments & consumption. Consequently, documentation is grossly inadequate and unit tests are not extensive. Both are areas that I hope to address, but time is working against me.

The best way to start using the components is to refer to code in the included `testapp` application. Each library feature is shown in a separate app page and can be seen by running the app (`ng serve`). The app's layout is driven by the `sp-mat-menu-layout` component which leverages material's sidemenu component to deliver a responsive hierarchical layout mechanism.

# Components

## qq-mat-file-input
A File Input Control that shows a thumbnail of the selected file. This can be
used wherever an <input matInput type='file'> is required.

## qq-mat-tel-input
A lightweight telephone numner input control that allows country selection by
typing the country name or country code.

Dependencies:
  * google-libphonenumber - ^3.2.34
  * ngx-mat-select-search - ^7.0.5


## qq-mat-menu-list-item
A primitive component for the `qq-mat-menu-pane` component that allows building
a side menu based UI. This component supports hierarchical relationship with
itself, in which case the the parent menu item componet will display a chevron
to indicate child menu items.

Menu item can specified as the `item` attribute value of type `NavItem`.

### Inputs

| Name | Description |
|------|-------------|
| item | `NavItem` object representing the menu item. |

### Color customization
Since application's UI (where this component will be typically used) would
require color customization, this component uses the following CSS variables
for its color.


| Variable | Description |
|----------|-------------|
| --qq-menu-item-bg-color | Menu item background color |
| --qq-menu-item-fg-color | Menu item foreground color |
| --qq-highlighted-menu-item-bg-color | Highlighted menu item background color |
| --qq-highlighted-menu-item-fg-color | Highlighted menu item foreground color |

## qq-mat-menu-pane
A parent container component that functions as the menu pane for the
`mat-sidenav` based user interface. The sidenav user interface (or layout),
consisting of a sidenav and a top toolbar, is wrapped as a component in
`sp-mat-menu-layout` described below.

This component takes an array of `NavItem` objects and renders it as the menu
in a container `div`. Typically this `div` will be hosted in a `mat-sidenav` as
part of an applications primary UI.

### Inputs

| Name | Description |
|------|-------------|
| brandingImage | Branding logo (32x32) that will be displayed on the top of the menu pane. |
| brandingText | Branding text that is displayed next to the logo on the top of the menu pane. |
| menuItems | Menu items which is an array of `NavItem` objects. |
| menuPaneFooterContent | `TemplateRef<>` content of which will be used as the footer at the bottom of the pane. |
| title | Title text displayed above the the menu items. |
| backButtonHref | If specified, the `href` for the back button displayed on the top. Will not be displayed if not set. |
| matSideNav | `MatSideNav` instance that will host the menu pane. |

### Example

See `mat-side-menu-layout` implementation for how this component is used.

## mat-side-menu-layout
A component that helps implement a side menu user interface with a top toolbar.
The layout is responsive and hides the side menu when run on small screens.
Toolbar displays the app title and on the right can accommodate buttons or any
other content (via content projection).

To use this component, initialize it with the branding logo & text, application
title and menu items (`NavItem[]`). This is the sample code from the example
in this repo: -
```
    <sp-mat-menu-layout
      brandingImage="assets/angular.png"
      brandingText="SMALLPEARL"
      appTitle="QQBOOKS"
      [menuItems]="menuItems"
      [menuPaneFooterContent]="versionInfoFooter"
      [toolbarTitleContent]="toolbarTitle"
    ></sp-mat-menu-layout>
    <ng-template #versionInfoFooter>
      <div style="text-align: center; font-size: 0.8em;">
        <select name="language" id="language">
          <option value="en">English</option>
          <option value="zh">中文</option>
        </select>
        <br />
        <small>2.3.102</small>
      </div>
    </ng-template>
    <ng-template #toolbarTitle>
      <button mat-button [matMenuTriggerFor]="otherCommunitiesMenu">
        <h4 class="community-name">Signature Park</h4>
        <mat-icon iconPositionEnd>arrow_drop_down</mat-icon>
      </button>
      <mat-menu #otherCommunitiesMenu="matMenu">
        <button mat-menu-item>Cavenagh Garden</button>
        <button mat-menu-item>Cashew Heights</button>
      </mat-menu>
    </ng-template>
        <ng-template #toolbarEndContent>
      <button mat-icon-button (click)="onNotificationsToggle()">
        <mat-icon>notifications</mat-icon>
      </button>
      <button
        mat-icon-button
        class="user-button"
        [matMenuTriggerFor]="userProfileMenu"
      >
        <img src="assets/avatar.jpg" alt="" />
      </button>
      <mat-menu #userProfileMenu="matMenu">
        <button mat-menu-item (click)="onUpdateProfile()">
          <mat-icon>face</mat-icon>
          <span>Profile</span>
        </button>
        <button mat-menu-item (click)="onChangePassword()">
          <mat-icon>password</mat-icon>
          <span>Change password</span>
        </button>
        <button mat-menu-item (click)="onSignOut()">
          <mat-icon>logout</mat-icon>
          <span>Sign out</span>
        </button>
      </mat-menu>
    </ng-template>
```

### Inputs
| Name | Type | Description |
|------|------|-------|
| showBackButton | boolean | A boolean property that controls if a Back button should be displayed at the top of the side menu. This is useful for secondary menus (note that this is NOT a submenu) from where a navigation path to the parent menu ought to be provided. |
| defaultBackButtonHref | string | The href for the back button is typically automatically determined. If there's no back history, the back button (if specified) will use this href. |
| brandingImage | string | Branding logo (32x32) that will be displayed on the top of the menu pane. |
| brandingText | string | Branding text that is displayed next to the logo on the top of the menu pane. |
| menuItems | NavItem[] | Menu items which is an array of `NavItem` objects. |
| appTitle | string | Application title. |
| menuPaneFooterContent | `TemplateRef<any>` | NgTemplate for the footer displayed below side menu. This will be passed to the `qq-mat-menu-pane`. |
| toolbarEndContent | `TemplateRef<any>` | NgTemplate for the content displayed at the end of the top toolbar. |
| infoPaneContent | `TemplateRef<any>` | NgTemplate for the content displayed in the information pane at the end of the page. |
| toolbarTitleContent | `TemplateRef<any>` | NgTemplate for the toolbar title. If specified, `appTitle` will be ignored. |
| infoPaneMinWidth | number | Minimum width of the info pane at the end of the page (right on LTR text). |
| infoPaneMaxWidth | number | Maximum width of the info pane at the end of the page (right on LTR text). |
| contentContainerClass | string | If specified, the CSS class that is applied to the content container div. This allows global styling of the container class (possibly padding, margin, color, etc) that will be applied to all the compoents corresponding to each menu item's link. |
| menuTitle | string | A title for the menu pane. Typically used in secondary side-menu layout pages. Defaults to an empty string. |

### CSS

| Variable | Description |
|----------|-------------|
| --qq-sidenav-bg-color | Sidenav menu pane background color |
| --qq-sidenav-fg-color | Sidenav menu pane foreground color |
| --qq-toolbar-bg-color | Toolbar background color |
| --qq-toolbar-fg-color | Toolbar foreground color |
| --qq-sidenav-border-color | Sidemenu border color |
| --qq-toolbar-border-color | Toolbar border color |
| --qq-menu-item-fg-color | Menu item foreground color |
| --qq-menu-item-bg-color | Menu item background color |
| --qq-highlighted-menu-item-fg-color | Highlighted menu item foreground color |
| --qq-highlighted-menu-item-bg-color | Highlighted menu item background color |

### Info pane

The component supports an information pane on the end of the pag. But it's
hidden by default and has to be explicitly shown. One way to do that would be
to query the `infoPane` member of `SPMatMenuLayoutComponent`
which is an instance of the `MatSideNav` component. You can toggle its
visibility by calling its `toggle()` method. An approach could be to show a
button at the end of the toolbar and then call `infoPane.toggle()` when the
button is selected.

```
  export class AppHomeComponent implements OnInit {
    @ViewChild(SPMatMenuLayoutComponent)
    sideMenuLayout: SPMatMenuLayoutComponent;

    ngOnInit(): void {}

    ...
    onNotificationsToggle() {
      if (this.sideMenuLayout) {
        this.sideMenuLayout.infoPane.toggle();
      }
    }
    ...
  }
```

## NavItem

This is the interface that is used to define the side menu items and pass it
as the value for the `menuItems` property. It is defined as:-

```
export interface NavItem {
  text: string;
  icon: string;
  iconType?: 'mat' | 'bi' | 'fa';
  disabled?: boolean;
  route?: string;
  children?: NavItem[];
  backButton?: boolean;
  backHref?: string;
}
```
Members are described in the following table:

| Member | Description |
|-------|----|
| text | The menu item text |
| icon | Icon displayed along with the text |
| iconType | One of {'mat'|'bi'|'fa'}. If not specified, defaults to 'mat' |
| disabled | Indicates that the menu item is disabled |
| route | The relative URL to navigate when the item is selected |
| children | If this item is a container for child menu items, set this to an array of `NavItem` objects |
| backButton | Used internally |
| backHref | Used internally |