npm package: @safetyio/ng-ui-components
Description: Please refer to the playground for further documentation.
Author: Safety IO GmbH
Latest version: 8.19.0

# Safety io UI Components

Please refer to the playground for further documentation.

## Installing the library

To install the library into your project please run `npm i @safetyio/ng-ui-components`

To include the playground icon-font and styles to your Angular project simply add the following import statement to your
(Angular) application styles.scss/styles.css file.

```scss
@import '../node_modules/@safetyio/ng-ui-components/sio-common.css';
@import '../node_modules/@safetyio/ng-ui-components/src/assets/styles/css/fonts/msa-icon-font/msa-icon-font.css';
```

**Important:** Native CSS imports must include the .css file extension. When it comes to importing SCSS, you should always utilize `@use` as recommended by [SASS guidelines](https://sass-lang.com/documentation/at-rules/import/).

Once the library is installed Sio modules and standalone components are available to be imported into your application.
These modules and components include:

```nolang
SioAlertsModule
SioBannersModule
SioButtonsModule
SioFormItemsModule
SioNavigationModule
SioChipsModule
SioProgressModule
SioPressureGagesModule
SioScrollersModule
SioTooltipDirective
SioChartsModule
SioAccordionModule
SioPasswordStrengthMeterModule
SelectComponent
OptionComponent
SioNavTabsComponent
```

Simply add these to the imports section of you `app.module.ts` file in your Angular application. The library
components will then be available to use.

### Font Requirements

The library uses the Roboto, Inter and Material Icons font. These are listed as `peerDependencies` and if not
already included in your application you will need to install them manually (this is due to npm no longer manually
installing peerDependencies).

## Available Components/Directives

### List of components/directives

The following components are available:

```nolang
<sio-alert>
<sio-banner>
<sio-chip>
[sioDefaultButton]
[sioInput]
[sioRadio]
[sioCheckbox]
<sio-side-menu>
<sio-tabs>
<sio-progress-bar>
<sio-dial-gage>
<sio-scroll-to-top>
[sioTooltip]
<sio-donut-chart>
<sio-spinner>
<sio-linear>
<sio-accordion>
<sio-toggle-menu>
[sio-slider]
[sioToggleOption]
<sio-nav-tabs>
```

### Components

The aforementioned components and directives have the following Input/Output structure, this is all documented in the playground.

#### sioToggleMenu (import entry `SioButtonsModule`)

```html
<sio-toggle-menu
  (toggleChange)="fn($event)"
  [buttonSize]="string"
  [selectedStyle]="'default' | 'primary'"
  [toggleStyle]="'default' | 'rounded'">
  <button>Option 1</button>
  <button>Option 2</button>
  <button (click)="fn($event)">Option 3</button>
</sio-toggle-menu>
```

#### sioToggleOption (import entry `SioButtonsModule`)

```html
<button [sioToggleOption]="T">Option 1</button>
```

#### sioAlert (import entry `SioAlertsModule`)

```html
<sio-alert
  [type]="'success' | 'info' | 'error' | 'alarm' | 'warn'"
  [heading]="string"
  [details]="boolean"
  [message]="string | HTML"
  [compact]="boolean"
  [pulse]="boolean">
  <!-- optional html or Angular Component if details === true -->
</sio-alert>
```

#### sioBanner (import entry `SioBannersModule`)

```html
<sio-banner
  [canClose]="boolean"
  [autoFade]="boolean"
  [sticky]="boolean"
  styling="string"
  type="string"
  message="string">
</sio-banner>
```

#### sioDefaultButton (import entry `SioBannersModule`)

```html
<button
  type="string"
  sioDefaultButton
  [fluid]="boolean"
  [buttonSize]="string"
  [buttonStyle]="string"
  [materialIcon]="string"
  [msaIcon]="string"
  [whiteIcon]="boolean"
  [rightMargin]="boolean"
  [rightIcon]="boolean"
  [rotate]="boolean"
  [toggleRotate]="boolean"
  [centered]="boolean">
  Button Text
</button>
```

#### sioInputDirective (import entry `SioFormItemsModule`)

```html
<input sioInput
  type="string"
  name="string"
  fill="flex | width"     
  placeholder="string"
  formControlName="string"
  [label]="'string'"
  [helperText]="'string'"
  [iconType]="IconType"
  [errors]="string[]"
  [iconPlacement]="IconPlacement">
```

Notice that this component uses the `IconType` and `IconPlacement` types which take the following structure:

```typescript
export type IconType = 'search' | 'email' | 'password' | 'clear';

export type IconPlacement = 'left' | 'right';
```

#### sioCheckboxDirective (import entry `SioFormItemsModule`)

```html
<input
  sioCheckbox
  [label]="'string'"
  [indeterminate]="boolean"
  [boldLabel]="boolean"
  [checked]="boolean">
```

#### sioNumberDirective (import entry `SioFormItemsModule`)

```html
<input
  sioNumber
  [controls]="boolean"
  [unit]="'string'"
  [subLabel]="'string'">
```

#### sioRadioDirective (import entry `SioFormItemsModule`)

```html
<input type="radio" sioRadio>
```

#### sioToggleSwitchDirective (import entry `SioFormItemsModule`)

```html
<input type="radio" sioToggleSwitch>
```

#### sioSelectDirective (import entry `SioFormItemsModule`)

```html
<select
  sioSelect
  selectPlaceholder="string"
  selectOptions="string[] & SioSelectOption[]">
  <option value="string">string</option>
</select>
```

Notice this uses an optional `SioSelectOption` type that takes the following structure:

```html
export interface SioSelectOption {
  label: string;
  value: any;
  selected?: boolean;
}
```

#### SelectComponent (standalone component)

```html
<!-- single choice select -->
<sio-select placeholder="Choose a number" [(ngModel)]="formValue">
  <sio-option>--</sio-option>
  <sio-option [value]="0">Zero</sio-option>
  <sio-option [value]="1">One</sio-option>
  <sio-option [value]="2">Two</sio-option>
</sio-select>

<!-- multiple choice select -->
<sio-select placeholder="Where do you want to go?" [(ngModel)]="formValue">
  <sio-option [value]="berlin">Berlin</sio-option>
  <sio-option [value]="london">London</sio-option>
  <sio-option [value]="paris">Paris</sio-option>
  <sio-option [value]="rome">Rome</sio-option>
</sio-select>
```

The component works with both Reactive and Template-driven form. It can also be used with two-way binding. It supports both single and multiple choice.

#### sioSliderDirective (import entry `SioFormItemsModule`)

```html
<input
      sioSlider
      type="range"
      min="number"
      max="number">
```

#### sioSideMenu (import entry `SioNavigationModule`)

```html
<sio-side-menu
  [showNavigation]="boolean"
  [menuOpen]="boolean"
  [routes]="routes"
  [activeRoute]="number"
  [closeLogo]="string"
  [openLogo]="string"
  (hrefClicked)="fn($event)">
</sio-side-menu>
```

Notice that this component uses the `routes` type which takes the following structure:

```typescript
export interface Route {
  id: string; // this is used within the template for submenus... must be unique and contain no spaces
  label: string;
  href?: string;
  icon?: string;
  children?: ChildRoute[];
}

export interface ChildRoute {
  label: string;
  href: string;
  icon?: string;
}
```

#### sioTabs (import entry `SioNavigationModule`)

```html
<sio-tabs [tabs]="tabs[]"
  [vertical]="boolean"
  [separate]="boolean"
  [tabWidth]="number"
  [indent]="boolean"
  [greyMode]="boolean"
  [contentPadding]="boolean"
  [noContentBorder]="boolean"
  [tabBackground]="string"
  [contentPaddingManual]="string"
  [initialTabIndent]="string"
  (clickedTab)="fn($event)">
</sio-tabs>

<!-- manual implementation -->
<sio-tabs [manual]="boolean" [tabs]="tabs[]">
  <div #manualcontents>Put content here</div>
</sio-tabs>
```

Notice this uses a `tabs` type that takes the following structure:

```typescript
export interface Tab {
  label: string;
  icon?: string;
  selected: boolean;
  html?: string;
  component?: ComponentReference;
  dataTest?: string;
  contentDataTest: string;
  inputs?: any; // object { key: value, key: value }
}
```

#### SioNavTabsComponent (import entry `SioNavTabsComponent`)

```html
<sio-nav-tabs [tabs]="tabs[]"></sio-nav-tabs>
```

Notice this uses a `tabs` type that takes the following structure:

```typescript
export type NavTab = {
  path: string;
  label: string;
  dataTest?: string;
};
```

#### sioChip (import entry `SioChipsModule`)

```html
<sio-chip
  label="string"
  chipType="string"
  chipStyle="string"
  [addSpacing]="boolean"
  [canClose]="boolean"
  [collapse]="boolean"
  [hideIcon]="boolean"
  [capitalise]="boolean"
  (chipClosed)="fn(foo)">
 </sio-chip>
```

#### sioProgressBar (import entry `SioProgressModule`)

```html
<sio-progress-bar max="number"
  value="number"
  type="string"
  [fluid]="boolean">
</sio-progress-bar>
```

#### sioDialGage (import entry `SioPressureGagesModule`)

```html
<sio-dial-gage
  [value]="number"
  [unit]="string"
  [maxValue]="number">
</sio-dial-gage>
```

#### sioScrollToTopComponent (import entry `SioScrollersModule`)

```html
<sio-scroll-to-top
  [positionLeft]="string"
  [positionBottom]="string"
  [fixed]="string"
  [animate]="boolean">
</sio-scroll-to-top>
```

#### sioTooltip (import entry `SioTooltipDirective`)

```html
<!-- can be any HTML element -->
<a href="#" sioTooltip="string | NgTemplate"></a>
```

#### SioDonutChartComponent (import entry `SioChartsModule`)

```html
<sio-donut-chart
  [type]="'success' | 'info' | 'error' | 'alarm' | 'warn'"
  [label]="string"
  [borderWidth]="string"
  [percentage]="number"
  [rounded]="boolean"
  [animate]="boolean">
</sio-donut-chart>
```

#### sioSpinner (import entry `SioProgressModule`)

```html
<sio-spinner
  [spinner]="'default' | 'stretch' | 'circle'"
  [size]="'small' | 'medium' | 'large' | 'xlarge'">
</sio-spinner>
```

#### sioLinear (import entry `SioProgressModule`)

```html
<sio-linear></sio-linear>
```

#### sioAccordion (import entry `SioAccordionModule`)

```html
<sio-accordion
  [heading]="string"
  [headingSize]="number"
  [isOpen]="boolean"
  [indent]="string">
  <!-- content here -->
</sio-accordion>
```

#### sioLoadingPlaceholder (import entry `LoadingPlaceholderDirective`)

```html
<div
  [sioLoadingPlaceholder]="boolean">
  <!-- content here -->
</div>
```

### Use of internal icon-font

The UI Components Library (@safetyio/ng-ui-components) has been upgraded so that it now contains a local version of the
MSA icon-font. The reasons for this were/are: The generator used in the exiting icon-font project
MsaIconFont was last published 7 years ago and has thus come to
the end of its lifecycle. The project was Ruby based whilst a NodeJS based project would be more inline with our
techstack. The names of the SVGs used to produce the icon-font followed no naming convention and thus the generated css
classes had no uniform naming convention. This has been resolved and is the main source of the breaking changes. thus
previous css class names like 'msa-No-Connection--2x' has been changed to 'msa-no-connection', A map for old to new CSS
classnames is provided. The final reason for the move was that moving the generated icon-font from one project to the
next and next was problematic and due to its many stages introduced risk. Moving the icon-font to the UI components
library removes the need to copy and paste the icon-font between projects. Increasing the number of icons to the
internal library is simplified and quickened.

A class name map is provided, you will need to find and replace the previous class names with the updated class names.
The object keys are the previous css name values, the object values are the new css class names. You will need
to do a find and replace within your host application to update your class name references or breakages will
occur.

```json
{
  "msa-360x1": "msa-360",
  "msa-360_hardware_error": "msa-360-hardware-error",
  "msa-2-way-communication-2x": "msa-two-way-communication",
  "msa-Admin--2x": "msa-admin",
  "msa-Cleaning": "msa-cleaning",
  "msa-Cloud": "msa-cloud",
  "msa-Color-2x": "msa-color",
  "msa-Filter---2x": "msa-filter",
  "msa-LTE-lost-signal-1x": "msa-lte-lost-signal",
  "msa-No-Connection--2x": "msa-no-connection",
  "msa-Persona-Remove-2x": "msa-persona-remove",
  "msa-SCBA-lost-connection": "msa-scba-lost-connection",
  "msa-SCBA-secondary": "msa-scba-secondary",
  "msa-STEL": "msa-stel",
  "msa-Shopping-Basket--2x": "msa-shopping-basket",
  "msa-TWA": "msa-twa",
  "msa-a4x_a5x_hardware_error": "msa-a4x-a5x-hardware-error",
  "msa-alarmBar": "msa-alarm-bar",
  "msa-alarmCircle": "msa-alarm-circle",
  "msa-arrow_circle_right": "msa-arrow-circle-right",
  "msa-arrow_left": "msa-arrow-left",
  "msa-arrow_right": "msa-arrow-right",
  "msa-assets-2x": "msa-assets",
  "msa-barcodeScan": "msa-barcode-scan",
  "msa-battery-powered-2x": "msa-battery-powered",
  "msa-bumpdue": "msa-bump-due",
  "msa-bluetoothCircle": "msa-bluetooth-circle",
  "msa-brightness-2x": "msa-brightness-2",
  "msa-calBottle": "msa-cal-bottle",
  "msa-calendarDue": "msa-calendar-due",
  "msa-calendarWarn": "msa-calendar-warn",
  "msa-checkList": "msa-checklist",
  "msa-closeCircle": "msa-close-circle",
  "msa-cloud_done": "msa-cloud-done",
  "msa-cloud_download": "msa-cloud-download",
  "msa-cloud_sync": "msa-cloud-sync",
  "msa-code_black": "msa-code",
  "msa-comments": "msa-comments",
  "msa-company-Info-2x": "msa-company-info",
  "msa-csv-document-2x": "msa-csv-document",
  "msa-customers-2x": "msa-customers",
  "msa-cylinder-empty--2x": "msa-cylinder-empty",
  "msa-cylinder-empty--horizontal-2x": "msa-cylinder-empty-horizontal",
  "msa-cylinder-empty-2x": "msa-cylinder-empty",
  "msa-cylinder-fills--2x": "msa-cylinder-fills",
  "msa-cylinder-fills-2x": "msa-cylinder-fills-horizontal",
  "msa-cylinder-fills--horizontal-2x": "msa-cylinder-fills-horizontal",
  "msa-data-2x": "msa-data-black",
  "msa-documents": "msa-document-black",
  "msa-document-configuration-2x": "msa-documents",
  "msa-documents2": "msa-document",
  "msa-donut_large": "msa-donut-large",
  "msa-donut_small": "msa-donut-small",
  "msa-download-alt-2x": "msa-download-2",
  "msa-evacuate-2x": "msa-evacuate",
  "msa-gasEmpty": "msa-gas-empty",
  "msa-gasLow": "msa-gas-low",
  "msa-general-device-2x": "msa-general-device",
  "msa-general-device-lost-connection-2x": "msa-general-device-lost-connection",
  "msa-get_out": "msa-get-out",
  "msa-hardware-error-1x": "msa-hardware-error",
  "msa-hardware-error-SCBA-2x": "msa-hardware-error-scba",
  "msa-hardware-error-lunar-2x": "msa-hardware-error-lunar",
  "msa-high_value": "msa-high-value",
  "msa-hydro-test--2x": "msa-hydro-test",
  "msa-iOSshare": "msa-ios-share",
  "msa-icEvent": "msa-ic-event",
  "msa-ic_exit_to_app": "msa-ic-exit-to-app",
  "msa-ic_wifi": "msa-ic-wifi",
  "msa-ic_wifi_lost": "msa-ic-wifi-lost",
  "msa-incidentsHistory": "msa-incidents-history",
  "msa-incomplete_circle": "msa-incomplete-circle",
  "msa-information-2x": "msa-information",
  "msa-instantalarm": "msa-instant-alarm",
  "msa-instrumentHistory": "msa-instrument-history",
  "msa-keyboard_arrow_down": "msa-keyboard-arrow-down",
  "msa-keyboard_black": "msa-keyboard-black",
  "msa-label-manager-2x": "msa-label-manager",
  "msa-languages-2x": "msa-languages",
  "msa-list-view-2x": "msa-list-view",
  "msa-liveData": "msa-live-data",
  "msa-low_value": "msa-low-value",
  "msa-lunar_lost_connection": "msa-lunar-lost-connection",
  "msa-maintenance-2x": "msa-maintenance",
  "msa-man-down-2x": "msa-man-down",
  "msa-mandown": "msa-mandown-label",
  "msa-manual-alarm--1x": "msa-manual-alarm",
  "msa-manufacturerCircle": "msa-manufacturer-circle",
  "msa-matClose": "msa-mat-close",
  "msa-matEmail": "msa-mat-email",
  "msa-matEye": "msa-mat-eye",
  "msa-matEyeOff": "msa-mat-eye-off",
  "msa-matKeyboardArrowDown": "msa-mat-keyboard-arrow-down",
  "msa-matRefresh": "msa-mat-refresh",
  "msa-matRightArrow": "msa-mat-right-arrow",
  "msa-matSearch": "msa-mat-search",
  "msa-menu-2x": "msa-menu",
  "msa-network-2x": "msa-network",
  "msa-news-2x": "msa-news",
  "msa-opticalScan": "msa-optical-scan",
  "msa-parts-2x": "msa-parts",
  "msa-pdf-document-2x": "msa-pdf-document",
  "msa-phonelink_erase": "msa-phonelink-erase",
  "msa-phonelink_lock": "msa-phonelink-lock",
  "msa-phonelink_off": "msa-phonelink-off",
  "msa-phonelink_ring": "msa-phonelink-ring",
  "msa-phonelink_setup": "msa-phonelink-setup",
  "msa-pin_number": "msa-pin-number",
  "msa-power-2x": "msa-power-2",
  "msa-print-2x": "msa-print-2",
  "msa-pulse_check": "msa-pulse-check",
  "msa-pumpfault": "msa-pump-fault",
  "msa-purchase-order-2x": "msa-purchase-order",
  "msa-qrCode": "msa-qr-code",
  "msa-radio_connection_repeater": "msa-radio-connection-repeater",
  "msa-refresh-2x": "msa-refresh",
  "msa-refreshCircle": "msa-refresh-circle",
  "msa-remove_outlined": "msa-remove-outlined",
  "msa-running-man-2x": "msa-running-man",
  "msa-sdCard": "msa-sd-card",
  "msa-search-2x": "msa-search",
  "msa-signal-celular-2x": "msa-signal-celular",
  "msa-sortAscending": "msa-sort-ascending",
  "msa-sortDescending": "msa-sort-descending",
  "msa-statistocs-2x": "msa-statistics",
  "msa-success-doble-check-2x": "msa-success-double-check",
  "msa-successCircle": "msa-success-circle",
  "msa-target-1x": "msa-target",
  "msa-temperature-2x": "msa-temperature",
  "msa-thumbtack-off-2x": "msa-thumbtack-off",
  "msa-thumbtack-on-2x": "msa-thumbtack-on",
  "msa-tile-view-2x": "msa-tile-view",
  "msa-toggle_on": "msa-toggle-on",
  "msa-track_changes": "msa-track-changes",
  "msa-upload-alt-2x": "msa-upload-alt",
  "msa-volume_level": "msa-volume-level",
  "msa-waiting-2x": "msa-waiting-2",
  "msa-wave_sensors": "msa-wave-sensors",
  "msa-wave-sensors": "msa-wave-sensors-off",
  "msa-work-Orders-2x": "msa-work-orders",
  "msa-work-folder-2x": "msa-work-folder",
  "msa-zoomToLocation": "msa-zoom-to-location",
  "msa-gas_bump-3x": "msa-gas-bump-icon",
  "msa-group3": "msa-group-tick"
}
```

Moving forward should you want to continue using the UI components library your application will have to update the css
class names for the msa icon-font. Should you not wish to do this then continue to use the MsaIconFont and continue to
use @safetyio/ng-ui-components 1.1.1.

The Grid team will no longer support the use of MsaIconFont with @safetyio/ng-ui-components