npm package: @maestroinfo/ngx-overlay
Description: A module to easily add open and manage overlays with injected components in your Angular application
Author: Domi Meister
Latest version: 1.0.1

Overlay

A module to create and manage overlays.

## Demo

A demo can be found here: https://ngx-overlay-demo.stackblitz.io

Stackblitz demo: https://stackblitz.com/edit/ngx-overlay-demo

## Installation

```bash
npm install --save @maestroinfo/ngx-overlay @angular/cdk
```

## Versions

- 1.0.1 - Angular 15

Simply import the OverlayModule from "@maestroinfo/ngx-overlay" in your AppModule. Any component that needs to be injected into the overlay needs to be placed into the entryComponents of a given module.

```typescript
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';
import { BrowserModule } from '@angular/platform-browser';

import { OverlayModule, OverlayService } from '@maestroinfo/ngx-overlay';
import { OverlayComponent } from './components/overlay.component';

@NgModule({
    imports: [BrowserModule, OverlayModule],
    declarations: [AppComponent, SidebarComponent],
    bootstrap: [AppComponent],
    providers: [OverlayService],
    entryComponents: [OverlayComponent],
})
export class AppModule {}
```

### Overlay styles

In order for the overlay to have the proper styles you must import @maestroinfo/overlay/base into your main style file.

```scss
@import '~@maestroinfo/ngx-overlay/styles/base.scss';
```

This is only needed if you don't use material theme already as it is included in the core.

### Opening an overlay

To open an overlay simply inject the overlay service into your component and trigger the open method on the class and pass in the component you want to inject.

```typescript
import { MstrOverlayRef, OverlayService } from '@maestroinfo/ngx-overlay';
...
constructor(private overlayService: OverlayService) {}
...
public openOverlay(): void {
  this.overlay.open(OverlayComponent);
}
```

### Configuring an overlay
When creating an overlay, an optional configuration object can be provided.

```typescript
  this.overlay.open(OverlayComponent, {
    panelClass: 'overlay',
    hasBackdrop: false,
    fullHeight: false,
    positionVertical: {
      placement: 'center'
    },
    positionHorizontal: {
      placement: 'center'
    },
  });
```


### Passing data to the injected component

In order to send data to the component that was opened simply pass in the config object with the parameter "data" with what ever data you want to share.

```typescript
this.overlay.open(OverlayComponent, { data: { menuItems: [] } });
```

You can then use this data within the injected component by using the MAESTRO_OVERLAY_DATA injection token

```typescript
export class OverlayComponent implements OnInit {
    constructor(
        public overlayRef: MstrOverlayRef,
        @Inject(MAESTRO_OVERLAY_DATA) public data: any
    ) {}

    ngOnInit() {
        console.log(this.data);
    }
}
```

### Closing an overlay

By default, the overlay will close automatically when the backdrop is pressed. If you want to manually close the overlay simply invoke the close method on the overlayRef

```typescript
export class SidebarComponent implements OnInit {
    constructor(
        public overlayRef: MstrOverlayRef,
        @Inject(MAESTRO_OVERLAY_DATA) public data: any
    ) {}

    closeSidebar() {
        this.overlayRef.close();
    }
}
```

Alternatively you can use the directive `mst-dialog-close` on a button to close a dialog

```html
<button mst-dialog-close>Close</button>
```

### Emitting a result outside the dialog

Is is possible to emit a result outside the overlay, i.e. when using the overlay as a confirm dialog.

```typescript
export class SidebarComponent implements OnInit {
    constructor(
        public overlayRef: MstrOverlayRef,
        @Inject(MAESTRO_OVERLAY_DATA) public data: any
    ) {}

    closeSidebar() {
        this.overlayRef.close(true);
    }
}
```

Or with the `mst-dialog-close` directive

```html
<button [mst-dialog-close]="true">Accept</button>
```

The result can be acted upon by subscribing to the `beforeClose` or `afterClose` events:

```typescript
const overlayRef = this.overlay.open(SidebarComponent);

overlayRef
    .afterClose()
    .subscribe(response =>
        console.log('Received result from overlay', response)
    );
```

### Animating in and out

In order to animate in, simply use the Angular Animations library to create a :enter animation.

#### Animating out

Animating out however is not as easy as a cause of the limitations within the CDK.

First you must add the following properties to your component.

```typescript
export class SidebarComponent implements MstrOverlayLeave {
  animationState: 'void' | 'enter' | 'leave' = 'enter';
  animationStateChanged = new EventEmitter<AnimationEvent>();
  ...
}
```

After that you must implement the following methods in your component.

```typescript
export class SidebarComponent implements MstrOverlayLeave {
  ...
  onAnimationStart(event: AnimationEvent) {
    this.animationStateChanged.emit(event);
  }

  onAnimationDone(event: AnimationEvent) {
    this.animationStateChanged.emit(event);
  }

  startExitAnimation() {
    this.animationState = 'leave';
  }
  ...
}
```

And finally you must implement the animation triggers for start and done on the element you trigger your animations on like this.

```html
<section [@slideContent]="animationState"
         (@slideContent.start)="onAnimationStart($event)"
         (@slideContent.done)="onAnimationDone($event)">
</section>
```

## Settings

At this time the service supports several config settings.

```typescript
export interface MstrOverlayConfig<T = any> {
    panelClass?: string | string[]; // Class around the panel wrapping the injected components (default: '')
    fullHeight?: boolean; // Decides if a panel should be full height or dependent on the component size (default: false)
    hasBackdrop?: boolean; // True/False if you want a backdrop or not (default: true)
    blockScroll?: boolean; // True/False if you want the backdrop to block scroll (default: true)
    backdropClass?: string; // Add a class to the backdrop (default: ''cdk-overlay-dark-backdrop)
    positionVertical?: {
        placement: 'bottom' | 'top' | 'center'; // Decides the vertical position of the component within the backdrop (default: 'center')
        offset?: string; // Offset can be in any given css unit. (default: '0px')
    };
    positionHorizontal?: {
        placement: 'left' | 'right' | 'center'; // Decides the horizontal position of the component within the backdrop (default: 'center')
        offset?: string; // Offset can be in any given css unit. (default: '0px')
    };
    positionStrategy?: PositionStrategy; // Provide either a CDK or a custom PositionStrategy (https://material.angular.io/cdk/overlay/api#PositionStrategy)
    scrollStrategy?: ScrollStrategy; // Provide either a CDK or a custom ScrollStrategy (https://material.angular.io/cdk/overlay/api#ScrollStrategy)
    data?: T; // Any data that should be injected into the component (default: {})
}
```