@safetyio/ng-ui-components

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.css file.

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

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

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.

Please note: The library uses the Roboto and Material Icons font. These are listed as a peerDependency 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:

<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)

<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)

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

sioAlert (import entry SioAlertsModule)

<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)

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

sioDefaultButton (import entry SioBannersModule)

<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)

<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:

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

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

sioCheckboxDirective (import entry SioFormItemsModule)

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

sioNumberDirective (import entry SioFormItemsModule)

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

sioRadioDirective (import entry SioFormItemsModule)

<input type="radio" sioRadio>

sioToggleSwitchDirective (import entry SioFormItemsModule)

<input type="radio" sioToggleSwitch>

sioSelectDirective (import entry SioFormItemsModule)

<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:

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

SelectComponent (standalone component)

<!-- 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)

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

sioSideMenu (import entry SioNavigationModule)

<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:

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)

<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:

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)

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

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

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

sioChip (import entry SioChipsModule)

<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)

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

sioDialGage (import entry SioPressureGagesModule)

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

sioScrollToTopComponent (import entry SioScrollersModule)

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

sioTooltip (import entry SioTooltipDirective)

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

SioDonutChartComponent (import entry SioChartsModule)

<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)

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

sioLinear (import entry SioProgressModule)

<sio-linear></sio-linear>

sioAccordion (import entry SioAccordionModule)

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

sioLoadingPlaceholder (import entry LoadingPlaceholderDirective)

<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.

{
'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