npm package: @ruc-lib/overlay
Description: 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.
Latest version: 4.0.0

# 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
```bash
npm install @uxpractice/ruc-lib
```

### Install Individual Component

If you only need the Overlay component:

**For Angular 15:**
```bash
npm install @ruc-lib/overlay@3.2.0 @angular/material@^15.0.0 @angular/cdk@^15.0.0
```

**For Angular 16:**
```bash
npm install @ruc-lib/overlay@3.2.0 @angular/material@^16.0.0 @angular/cdk@^16.0.0
```

**For Angular 17:**
```bash
npm install @ruc-lib/overlay@4.0.0 @angular/material@^17.0.0 @angular/cdk@^17.0.0
```

**For Angular 18:**
```bash
npm install @ruc-lib/overlay@4.0.0 @angular/material@^18.0.0 @angular/cdk@^18.0.0
```

**For Angular 19:**
```bash
npm install @ruc-lib/overlay@4.0.0 @angular/material@^19.0.0 @angular/cdk@^19.0.0
```

**For Angular 20:**
```bash
npm install @ruc-lib/overlay@4.0.0
```

> **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`:

```typescript
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
<link href="https://fonts.googleapis.com/css2?family=Material+Icons&display=swap" rel="stylesheet">

### 4. Use the Component
In your component's template, use the `<uxp-ruclib-overlay>` selector and pass the configuration object to the `rucInputData` input.


```html
<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.

```typescript
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);
}


}
```

```html
<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!