npm package: @ngxhelpers/overlay
Description: This service provides a convenient way to create and manage overlays (like modals, dropdowns, popovers, and tooltips) in your Angular application. It builds upon Angular CDK's Overlay module, adding simplified configuration and management.
Latest version: 1.0.6

# NgxOverlay Service

This service provides a convenient way to create and manage overlays (like modals, dropdowns, popovers, and tooltips) in your Angular application. It builds upon Angular CDK's Overlay module, adding simplified configuration and management.

## Installation

```bash
npm install @ngxhelpers/overlay
```

## Usage

1. **Import `NgxOverlay` and inject it into your component:**

    ```typescript
    import { NgxOverlay } from '@ngxhelpers/overlay'; // Assuming you've published/imported the library

    constructor(private overlay: NgxOverlay) {}
    ```

2. **Use the `open` method to create an overlay:**

    ```typescript
    const overlayRef = this.overlay.open({
    	component: MyComponent, // Or TemplateRef, HTMLElement, ElementRef
    	data: { message: 'Hello from overlay!' }, // Optional data
    	position: 'center', // Or 'topLeft', 'topRight', 'bottomLeft', 'bottomRight', 'dropdown', 'popover', or a custom PositionStrategy
    	origin: this.elementRef, // Optional origin element for positioning (important for 'dropdown' and 'popover')
    	options: {
    		hasBackdrop: true,
    		panelClass: ['my-overlay-class'], // Optional
    		backdropClass: ['my-backdrop-class'], // Optional
    		width: '300px' // Optional
    		// ... other NgxOverlayConfigOptions
    	}
    });

    // Access the component instance (if applicable)
    overlayRef.componentInstance?.myMethod();

    // Close the overlay programmatically
    overlayRef.close();

    // Subscribe to the afterClosed event (when the overlay closes)
    overlayRef.afterClosed.subscribe((result) => {
    	console.log('Overlay closed', result);
    });
    ```

## API Reference

### `open<T, R = any>(params: NgxOverlayParams<T>): NgxOverlayRef<T, R>`

Creates an overlay.

**Parameters:**

-   `params: NgxOverlayParams<T>`: An object with the following properties:

    -   `component: Type<T> | TemplateRef<any> | HTMLElement | ElementRef`: The component, template, or HTML element to display in the overlay.
    -   `data: any`: (Optional) Data to pass to the overlay component or template (accessible via the `NGX_OVERLAY_DATA` injection token).
    -   `position: NgxDefaultOverlayPositions | PositionStrategy`: The position of the overlay. Can be one of the predefined positions ('center', 'topLeft', etc.) or a custom `PositionStrategy`.
    -   `origin: ElementRef<HTMLElement> | HTMLElement`: (Optional, required for 'dropdown' and 'popover' positions) The origin element for positioning the overlay.
    -   `options: NgxOverlayConfigOptions`: (Optional) Additional options for configuring the overlay (see below).

### `dispose(disposeClass?: string): void`

Destroys the overlay. Can destroy a specific overlay using its panel class or destroy all if no id is passed.

### `openHover<T, R = any>(params: NgxOverlayParams<T>): NgxOverlayRef<T, R>`

Creates a hover overlay using similar parameters to the main open method. Intended for creating pop-up elements on mouse hover.

**Parameters:**

-   `params: NgxOverlayParams<T>`: Same parameters as the `open` method.

### `disposeHover(data?: string): void`

Closes a hover overlay. If no data is passed, disposes of all hover overlays. Useful for closing pop-up elements when the mouse pointer leaves a trigger element.

### `NgxOverlayConfigOptions`

The `options` parameter in the `open` and `openHover` methods accepts an object of type `NgxOverlayConfigOptions`:

-   `hasBackdrop: boolean`: Whether the overlay should have a backdrop. Defaults to `false`.
-   `panelClass: string | string[]`: Custom CSS class(es) to apply to the overlay panel.
-   `backdropClass: string | string[]`: Custom CSS class(es) to apply to the backdrop.
-   `width: string | number`: Width of the overlay panel.
-   `height: string | number`: Height of the overlay panel.
-   `minWidth: string | number`: Minimum width of the overlay panel.
-   `minHeight: string | number`: Minimum height of the overlay panel.
-   `maxWidth: string | number`: Maximum width of the overlay panel.
-   `maxHeight: string | number`: Maximum height of the overlay panel.
-   `boundBoxClass: string`: Apply a class to the overlay bounding box element.
-   `disposeClass: string`: A class to reference while closing or disposing a specific overlay. Defaults to `''`.
-   `outsideClick: boolean`: Closes overlay on outside click event. Defaults to `false`.
-   `closePrevious: boolean`: Closes previously opened overlays or instances. Default is `true`.
-   `containerRef: ViewContainerRef`: (Optional) If not set default set to global level viewref. Used for dynamically injecting content into specific areas of your application. Provide a `ViewContainerRef` to control where the overlay is rendered.
-   `content: any`: (Optional) For using TemplateRef as a container.

### `NgxOverlayRef<T, R = any>`

The `open` method returns an `NgxOverlayRef` object, which provides methods for interacting with the overlay:

-   `close(data?: R): void`: Closes the overlay and optionally passes data back to the component that opened it.
-   `afterClosed: Subject<R | undefined>`: An observable that emits when the overlay is closed, optionally with data passed from the `close` method.
-   `componentInstance: T | undefined`: A reference to the component instance created inside the overlay (if applicable).
-   `origin?: ElementRef<HTMLElement> | HTMLElement | HTMLDivElement`: Reference to origin element of overlay.

### Predefined Positions (`NgxDefaultOverlayPositions`)

-   `'center'`: Centers the overlay horizontally and vertically on the screen.
-   `'topLeft'`: Positions the overlay at the top-left corner of the screen.
-   `'topRight'`: Positions the overlay at the top-right corner of the screen.
-   `'bottomLeft'`: Positions the overlay at the bottom-left corner of the screen.
-   `'bottomRight'`: Positions the overlay at the bottom-right corner of the screen.
-   `'dropdown'`: Positions the overlay below the origin element, like a dropdown. Requires the `origin` parameter.
-   `'popover'`: Positions the overlay near the origin element, like a popover. Requires the `origin` parameter.

### Custom Positioning

For more advanced positioning, you can create a custom `PositionStrategy` using the Angular CDK's `Overlay` module directly and pass it to the `position` parameter. Refer to the Angular CDK documentation for details on creating custom position strategies.