npm package: @ruc-lib/dialog
Description: This library provides a flexible and customizable dialog component for your Angular applications. Users can integrate the dialog component using Angular services or selectors with ease. Below are the features, usage instructions, and integration details
Latest version: 4.0.0

# ruclib-dialog

This library provides a flexible and customizable dialog component for your Angular applications. Users can integrate the dialog component using Angular services or selectors with ease. Below are the features, usage instructions, and integration details

# Installation Guide

To use the Dialog 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 Dialog component:

**For Angular 15:**
```bash
npm install @ruc-lib/dialog@3.2.0 @angular/material@^15.0.0 @angular/cdk@^15.0.0
```

**For Angular 16:**
```bash
npm install @ruc-lib/dialog@3.2.0 @angular/material@^16.0.0 @angular/cdk@^16.0.0
```

**For Angular 17:**
```bash
npm install @ruc-lib/dialog@4.0.0 @angular/material@^17.0.0 @angular/cdk@^17.0.0
```

**For Angular 18:**
```bash
npm install @ruc-lib/dialog@4.0.0 @angular/material@^18.0.0 @angular/cdk@^18.0.0
```

**For Angular 19:**
```bash
npm install @ruc-lib/dialog@4.0.0 @angular/material@^19.0.0 @angular/cdk@^19.0.0
```

**For Angular 20:**
```bash
npm install @ruc-lib/dialog@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/dialog` based on your Angular version. 

| Angular Version    | Compatible `@ruc-lib/dialog` Version     |
|--------------------|------------------------------------------|
| 15.x.x             | `npm install @ruc-lib/dialog@^3.2.0`     |
| 16.x.x             | `npm install @ruc-lib/dialog@^3.2.0`     |
| 17.x.x             | `npm install @ruc-lib/dialog@^4.0.0`     |
| 18.x.x             | `npm install @ruc-lib/dialog@^4.0.0`     |
| 19.x.x             | `npm install @ruc-lib/dialog@^4.0.0`     |
| 20.x.x             | `npm install @ruc-lib/dialog@^4.0.0`     |


## Usage

To use the dialog component in your project, follow the integration guidelines provided in the documentation. Customize the dialog as per your requirements by adjusting the configuration options mentioned below.

## Using Dialog Service

1.	Import `ViewContainerRef` from `@angular/core`.
2.	Import `DialogService` from `"@ruc-lib/dialog"`.
3.	Inject `DialogService` and `ViewContainerRef` into your component constructor.
4.	Call open method of `DialogService` with `ViewContainerRef` and dialog data.
5.	Subscribe to `afterClosed` to get the result after dialog closure.

Example:

```typescript
import { Component } from "@angular/core";
import { ViewContainerRef } from "@angular/core";

// For Complete Library
import { DialogService } from "@uxpractice/ruc-lib";

// For Individual package
import { DialogService } from "@ruc-lib/dialog";

@Component({
    selector: "app-my-component",
    templateUrl: "./my-component.component.html"
})
export class MyComponent {
   constructor(
        public dialogService: DialogService,
        private viewContainerRef: ViewContainerRef
    ) {}
    openDialog(data: any): void {
        this.dialogService.open(this.viewContainerRef, data)
            ?.afterClosed()
            .subscribe((res: any) => {
                console.log(res);
            });
    }
}
```


## Using Selector

1.	Import `DialogModule` into `app.module.ts` file. 
`import { RuclibDialogModule } from '@ruc-lib/dialog';`
OR
`import { RuclibDialogModule } from '@ uxpractice /ruc-lib/dialog';`
2.	Use the dialog selector in your HTML file.
3.	Handle input and output bindings accordingly.

Example:
in app.module.ts

```typescript
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
// For complete Library
import { RuclibDialogModule } from '@uxpractice/ruc-lib/dialog';

// For Individual package
import { RuclibDialogModule } from '@ruc-lib/dialog';

import { AppComponent } from './app.component';

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    RuclibDialogModule
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }
```

in app.component.html

```html
<uxp-ruclib-dialog 
    (rucEvent)="passEvent($event)" 
    [buttonText]="ButtonLabelDialog"
    [rucInputData]="inputObjectDataDialog" 
    [customTheme]="customTheme">
</uxp-ruclib-dialog>
```

## API Reference

### Component Inputs


## Input and Output

| Input          | Type                     | Description                                       |
|----------------|--------------------------|---------------------------------------------------|
| `rucInputData` | `DialogDefaultConfig`    | The main configuration object for the dialog.     |
| `customTheme`  | `string`                 | An optional CSS class for custom theming.         |
| `buttonText`   | `string`                 | Text for the action buttons.                      |

### Component Outputs

| Output     | Type      | Description                                       |
|------------|-----------|---------------------------------------------------|
| `rucEvent` | `any`     | Event emitted from the dialog. |

### `DialogDefaultConfig`
This is the main configuration object for the Dialog component.

| Property                | Type                             | Description                                                                                |
|-------------------------|----------------------------------|--------------------------------------------------------------------------------------------|
| type                    | 'alert' \| 'prompt' \| 'confirm' | Type of dialog                                                                             |
| title                   | string                           | Title of the dialog.                                                                       |
| content                 | string                           | Content of the dialog.                                                                     |
| buttons                 | DialogBoxButton[]                | Array of buttons. Ex: [{ name: 'Yes', color: '', behaviour: 'Submit', btnType:'stroked' }] |
| id                      | number                           | Unique identifier for the dialog.                                                          |
| displayCloseButton      | boolean                          | Whether to display the close button.                                                       |
| movableDialog           | boolean                          | Whether the dialog is movable.                                                             |
| hasBackdrop             | boolean                          | Whether to display a backdrop.                                                             |
| closeOnClickAndEscape   | boolean                          | Whether to close the dialog on click.                                                      |
| fullScreenDialog        | boolean                          | Whether the dialog is full screen.                                                         |
| direction               | string                           | Direction of the dialog. Ex, 'center'                                                      |
| header                  | boolean                          | Whether to display the header.                                                             |
| width                   | string                           | Width of the dialog.                                                                       |
| height                  | string                           | Height of the dialog.                                                                      |
| maxHeight               | string                           | Maximum height of the dialog.                                                              |
| maxWidth                | string                           | Maximum width of the prompt.                                                               |
| autoFocus               | boolean                          | For prompt, to focus the first input element.                                              |
| autoComplete            | boolean                          | Whether to enable auto-completion.                                                         |
| autoCompleteList        | any                              | List of auto-complete options.                                                             |
| theme                   | string                           | Theme for the Prompt.                                                                      |
| defaultPromptValue      | string                           | Default value for the prompt input.                                                        |
| contentAlignment        | string                           | Alignment of the content.                                                                  |
| customComponentName     | any                              | Custom component name.                                                                     |
| contentAlignDirection   | string                           | Direction of the content alignment.                                                        |
| buttonsPosition         | 'left' \| 'right'                | Position of the buttons.                                                                   |
| showButtonsVertically   | boolean                          | Whether to show buttons vertically.                                                        |
| backdropClass           | string                           | CSS class for the backdrop.                                                                |
| btnType                 | string                           | Type of the button.                                                                        |
| customTheme             | string                           | Custom theme for the dialog.                                                               |


## Example Configuration
Here's an example of how to configure the Dialog component in your component's TypeScript file.


```typescript
import { Component } from '@angular/core';

// For Complete Library
import {DialogDefaultConfig} from '@uxplib/ruc-lib/dialog';

// For Individual package
import {DialogDefaultConfig} from '@ruc-lib/dialog';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
})
export class AppComponent {
    inputObjectDataDialog: DialogDefaultConfig = {
        title: 'RUC Dialog',
        content: 'This is RUC Dialog Content.',
        buttons: [{ name: 'Yes', color: '', behaviour: 'Submit', btnType: 'stroked' }],
        id: 1,
        type: 'confirm',
        displayCloseButton: true,
        movableDialog: true,
        hasBackdrop: false,
        closeOnClickAndEscape: true,
        fullScreenDialog: false,
        direction: 'center',
        header: true,
        width: '350px',
        height: '',
        maxHeight: '',
        maxWidth: '',
        autoFocus: true,
        theme: '',
        defaultPromptValue: 'Enter Name',
        contentAlignDirection: 'left', // ToDO
        buttonsPosition: 'left',
        showButtonsVertically: false,
        backdropClass: 'backdropClass',
        customTheme: 'custom-theme'
    }

    passEvent(event: any) {
        console.log('Dialog Event:', event);
    }
}
```

> ⚠️ **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 Dialog Component Library. If you have any feedback or suggestions, please let us know!