Overlay

A customizable Angular overlay component that display richer content, such as text, images, tables, charts and more. They are useful for providing additional information to users without cluttering the interface.

Installation Guide

To use the Overlay component, you can install the entire RUC library or just this specific component.

Install the Entire Library

npm install @uxpractice/ruc-lib

Install Individual Component

If you only need the Overlay component:

For Angular 15:

npm install @ruc-lib/[email protected] @angular/material@^15.0.0 @angular/cdk@^15.0.0

For Angular 16:

npm install @ruc-lib/[email protected] @angular/material@^16.0.0 @angular/cdk@^16.0.0

For Angular 17:

npm install @ruc-lib/[email protected] @angular/material@^17.0.0 @angular/cdk@^17.0.0

For Angular 18:

npm install @ruc-lib/[email protected] @angular/material@^18.0.0 @angular/cdk@^18.0.0

For Angular 19:

npm install @ruc-lib/[email protected] @angular/material@^19.0.0 @angular/cdk@^19.0.0

For Angular 20:

npm install @ruc-lib/[email protected]

Note: When installing in Angular 15-19 apps, you must specify the matching @angular/material and @angular/cdk versions to avoid peer dependency conflicts. Angular 20 will automatically use the correct versions.

Version Compatibility

Please ensure you install the correct version of @ruc-lib/overlay based on your Angular version.

| Angular Version | Compatible @ruc-lib/overlay Version | |--------------------|-------------------------------------------| | 15.x.x | npm install @ruc-lib/overlay@^3.2.0 | | 16.x.x | npm install @ruc-lib/overlay@^3.2.0 | | 17.x.x | npm install @ruc-lib/overlay@^4.0.0 | | 18.x.x | npm install @ruc-lib/overlay@^4.0.0 | | 19.x.x | npm install @ruc-lib/overlay@^4.0.0 | | 20.x.x | npm install @ruc-lib/overlay@^4.0.0 |

Usage

1. Import the Component

In your Angular component file (e.g., app.component.ts), import the RuclibOverlayComponent:

import { Component } from '@angular/core';

// For Complete Library
import { RuclibOverlayComponent } from '@uxpractice/ruc-lib/overlay';

// For Individual Package
import { RuclibOverlayComponent } from '@ruc-lib/overlay';

@Component({
  selector: 'app-root',
  imports: [RuclibOverlayComponent],
  templateUrl: './app.component.html',
})
export class AppComponent {
  // Component code here
}

2. Update the style.scss file

@use 'sass:map'; @use '@angular/material' as mat; @include mat.core();

3. Include material icon cdn in your index.html

4. Use the Component

In your component's template, use the <uxp-ruclib-overlay> selector and pass the configuration object to the rucInputData input.

<uxp-ruclib-overlay [rucInputData]="OverlayConfig"></uxp-ruclib-overlay> 

API Reference

Component Inputs

| Input | Type | Description | |----------------|--------------------|----------------------------------------------| | rucInputData | OverlayConfig | The main configuration object for the component. | | customTheme | string | An optional CSS class for custom theming. |

OverlayConfig

This is the main configuration object for the overlay

| Property | Type | Description | |-----------------------------|--------------------------------------------------|---------------------------------------------------------------------------------------------------------| | placement | 'bottom' \| 'top' \| 'left' \| 'right' | The position of the overlay content (e.g., 0). | | trigger | 'click'\|'hover' \ | The maximum value of the progress bar (e.g., 100). | | overlayTitle | string | The title of the overlay content. | | content | 'string' \| templateRef | If accept string or html template both of displaying the content inside overlay area. | | animation | 'fade' \| 'scale' \| | The animation type for the overlay content (e.g., 'fade', 'scale').. Defaults to fade. | | showCloseButton | boolean | It close the overlay.. Defaults to false. | | closeIcon | string | Icon class for the close button. User can give his own icon for close the overlay. | | tableData | any[] | It accept array of object and display data in table format inside overlay. | | tableClass | 'basic-table' \|'striped-table' \| | It accept table styling class .. Defaults to basic-table. | | closeDelay | number | it delay the overlay close(milliseconds). | | chartConfig | any | it can display chart if user provide chart configuration. |

Example Configuration

Here's an example of how to configure the Overlay in your component's TypeScript file.

import { Component, AfterViewInit, ViewChild, TemplateRef } from '@angular/core';
import { OverlayConfig, OverlayService } from '@ruc-lib/overlay';

export const chartConfig = {
  doughnut: {
    type: 'doughnut',
    data: {
      labels: [
        'Red',
        'Blue',
        'Yellow'
      ],
      datasets: [{
        label: '',
        data: [300, 50, 100],
        backgroundColor: [
          'rgb(255, 99, 132)',
          'rgb(54, 162, 235)',
          'rgb(255, 205, 86)'
        ],
        hoverOffset: 4
      }]
    },
    options: {
      cutout: 70,
      // rotation: -Math.PI / 2,
      // circumference: Math.PI,
      legend: {
        display: false,
      },
    },
  }
}

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
})
export class AppComponent implements AfterViewInit {
  overlayConfig: OverlayConfig = {
    placement: 'left',
    overlayTitle: 'Animated Popover with fade',
    content: 'This is a simple popover triggered by a click.',
    trigger: 'click',
    animation: 'fade',
    closeIcon: 'close',
    showCloseButton : true,;
  };

  overlayBasicTableConfig:OverlayConfig  = {
    placement: 'top',
    overlayTitle: 'User Data',
    content: '', // Not used when tableData is present
    showCloseButton: true,
    tableData: [
     { id: 1, firstName: 'John', lastName: 'Doe', role: 'Admin' },
    { id: 2, firstName: 'Jane', lastName: 'Smith', role: 'User' },
    { id: 3, firstName: 'Peter', lastName: 'Jones', role: 'Editor' },
    { id: 1, firstName: 'John', lastName: 'Doe', role: 'Admin' },
    { id: 2, firstName: 'Jane', lastName: 'Smith', role: 'User' },
    { id: 3, firstName: 'Peter', lastName: 'Jones', role: 'Editor' },
    { id: 1, firstName: 'John', lastName: 'Doe', role: 'Admin' },
    { id: 2, firstName: 'Jane', lastName: 'Smith', role: 'User' },
    { id: 3, firstName: 'Peter', lastName: 'Jones', role: 'Editor' },
    ],
    tableClass: 'basic-table'
  };

  //for custom template
  templateConfig:OverlayConfig  = {
    placement: 'top',
    overlayTitle: 'Custom Template Content',
    showCloseButton: true,
    content: '' // Placeholder, will be replaced in ngOnInit
  };

  //for chart config
  doughnutPopoverConfig:OverlayConfig = {
     placement: 'bottom',
     overlayTitle: 'Doughnut Chart Popover',
     content: '',
     trigger: 'click',
     animation: 'fade',
     closeIcon: 'remove',
     showCloseButton : true,
     chartConfig:chartConfig.doughnut//you can provide chart.js configuration here.
   };


  @ViewChild('myCustomTemplate', {static:false}) myCustomTemplateRef! : TemplateRef<any>
  @ViewChild('serviceCustomTemplate', {static:false}) serviceCustomTemplate! : TemplateRef<any>
  public finalTemplateConfig:any;

  serviceStringConfig:OverlayConfig  = {
    placement: 'left',
    overlayTitle: 'Service Popover',
    content: 'I was opened by the service with close icon.',
    closeIcon: 'close', // Assuming you have Font Awesome installed
    animation: 'fade'
  };

    constructor(
    public overlayService:OverlayService
  ) { }

    ngAfterViewInit(): void {
    //prepare the final config object here
    //this runs after the @viewchild ready
    this.finalTemplateConfig = {
      ...this.mockTemplateConfig,
      content : this.myCustomTemplateRef
    }
  }

  // Service-Controlled Overlay
  openServiceString(trigger :HTMLElement) {
    this.overlayService.open(this.serviceStringConfig, trigger);
  }

//Service-Controlled - template
  openServiceTemplate(trigger: MatButton | HTMLElement) {
  const triggerElement = trigger instanceof MatButton ? trigger._elementRef.nativeElement : trigger;
  const configForTemplate = {
    placement: 'left',
    overlayTitle: 'Dynamic Template via Service',
    showCloseButton: true,
    closeIcon: 'close',
    content: this.serviceCustomTemplate
  };
  this.overlayService.open(configForTemplate, triggerElement);
}


}

<uxp-ruclib-overlay [rucInputData]="overlayConfig"></uxp-ruclib-overlay>

<uxp-ruclib-overlay [rucInputData]="overlayBasicTableConfig"></uxp-ruclib-overlay>

<uxp-ruclib-overlay [buttonText]="'Doughnut Chart Overlay'" [rucInputData]="doughnutPopoverConfig" ></uxp-ruclib-overlay>

<!--custom template selector-->
<uxp-ruclib-overlay [buttonText]="'Custom Template'" [rucInputData]="finalTemplateConfig"></uxp-ruclib-overlay>
<!--custom template-->
 <ng-template #myCustomTemplate>
    <div>
      In Angular, a custom template using templateRef is a reusable section of HTML that can be referenced and rendered within a component.
    </div>
  </ng-template>


  <!--Service controlled overlay-->
  <!--Below is the mandatory receiver for service controlled overlay-->
   <uxp-ruclib-overlay></uxp-ruclib-overlay>
   <!--------->
  <a href="javascript:void(0);" #serviceStringConfig (click)="openServiceString(serviceStringConfig)"> Click Me </a>

  <button
  mat-raised-button
  color="accent"
  #serviceTemplateTrigger="matButton"
  (click)="openServiceTemplate(serviceTemplateTrigger)">
  Trigger Service (Template)
</button>
  <!---->

> ⚠️ **IMPORTANT: Custom Theme Usage in Angular Material**

When implementing **custom themes**, such as:

```scss
.custom-theme-1 {
  @include angular-material-theme($custom-theme);
}

// You must also include the typography mixin to ensure text styles are applied correctly as shown below:
.custom-theme-1 {
  @include angular-material-theme($custom-theme);
  @include mat.typography-level($theme-custom-typography-name, body-1);
}

Contribution

Contributions are welcome! Feel free to open issues or pull requests for any enhancements or fixes.

Acknowledgements

Thank you for choosing the Overlay component. If you have any feedback or suggestions, please let us know!