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

npm install @uxpractice/ruc-lib

Install Individual Component

If you only need the Dialog 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/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:

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

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

<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.

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:

.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!