npm package: @ruc-lib/context-menu
Description: This library provides a flexible and customizable context menu 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 det
Latest version: 4.0.0

# ruclib-context-menu

This library provides a flexible and customizable context menu 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 Context Menu 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 ContextMenu component:

**For Angular 15:**
```bash
npm install @ruc-lib/context-menu@3.2.0 @angular/material@^15.0.0 @angular/cdk@^15.0.0
```

**For Angular 16:**
```bash
npm install @ruc-lib/context-menu@3.2.0 @angular/material@^16.0.0 @angular/cdk@^16.0.0
```

**For Angular 17:**
```bash
npm install @ruc-lib/context-menu@4.0.0 @angular/material@^17.0.0 @angular/cdk@^17.0.0
```

**For Angular 18:**
```bash
npm install @ruc-lib/context-menu@4.0.0 @angular/material@^18.0.0 @angular/cdk@^18.0.0
```

**For Angular 19:**
```bash
npm install @ruc-lib/context-menu@4.0.0 @angular/material@^19.0.0 @angular/cdk@^19.0.0
```

**For Angular 20:**
```bash
npm install @ruc-lib/context-menu@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

| Angular Version | Compatible Version | Installation Command                                                                      |
|-----------------|--------------------|-------------------------------------------------------------------------------------------|
| 15.x.x          | 3.2.0              | `npm install @ruc-lib/context-menu@^3.2.0 @angular/material@^15.0.0 @angular/cdk@^15.0.0` |
| 16.x.x          | 3.2.0              | `npm install @ruc-lib/context-menu@^3.2.0 @angular/material@^16.0.0 @angular/cdk@^16.0.0` |
| 17.x.x          | 4.0.0              | `npm install @ruc-lib/context-menu@^4.0.0 @angular/material@^17.0.0 @angular/cdk@^17.0.0` |
| 18.x.x          | 4.0.0              | `npm install @ruc-lib/context-menu@^4.0.0 @angular/material@^18.0.0 @angular/cdk@^18.0.0` |
| 19.x.x          | 4.0.0              | `npm install @ruc-lib/context-menu@^4.0.0 @angular/material@^19.0.0 @angular/cdk@^19.0.0` |
| 20.x.x          | 4.0.0              | `npm install @ruc-lib/context-menu@^4.0.0`                                                |


## Usage
### 1. Import the Component
In your Angular component file (e.g., `app.component.ts`), import the `RuclibContextMenuComponent`:

```typescript
import { Component } from '@angular/core';

// For Complete Library
import { RuclibContextMenuComponent } from '@uxpractice/ruc-lib/context-menu';

// For Individual Package
import { RuclibContextMenuComponent } from '@ruc-lib/context-menu';

@Component({
  selector: 'app-root',
  imports: [RuclibContextMenuComponent],
  templateUrl: './app.component.html',
})
export class AppComponent {
  // Component code here
}
```

### 2. Use the Component
In your component's template, use the `<uxp-ruclib-context-menu>` selector and pass the configuration object to the `rucInputData` input and the data array to the `dataSource` input.

```html
<uxp-ruclib-context-menu [rucInputData]="inputContextData"(rucEvent)="passEvent($event)"></uxp-ruclib-context-menu>
```

## API Reference

### Component Inputs

| Input             | Type               | Description                                         |
|-------------------|--------------------|-----------------------------------------------------|
| `rucInputData`    | `inputContextData` | The main configuration object for the Context Menu. |
| `customTheme`     | `string`           | An optional CSS class for custom theming.           |

### Component Outputs

| Output            | Type              | Description                                           |
|-------------------|-------------------|-------------------------------------------------------|
| `rucEvent`        | `any`             | Emits events related to Context Menu actions          |

### `inputContextData`
This is the main configuration object for the Context Menu component.

| Property                  | Type      | Description                                                               |
|---------------------------|-----------|---------------------------------------------------------------------------|
| `type`                    | `string`  | Type of Context Menu. It can be icon, button, image                       |
| `matIconName`             | `string`  | When Type is icon then matIconName is used for icon name.                 |
| `matButtonColor`          | `string`  | When Type is button then matButtonColor is used for button type.          |
| `matButtonLabelName`      | `string`  | When Type is button then matButtonColor is used for Button Label.         |
| `imgUrl`                  | `string`  | When Type is image then imgUrl is used for image source.                  |
| `alternateImg`            | `string`  | When Type is image then alternateImg is used if image is not available.   |
| `contextMenuData`         | `string`  | Change the alignment of step count.                                       |
| `xPosition`               | `string`  | To set x-poition of context menu. It can be before or after               |
| `yPosition`               | `string`  | To set y-poition of context menu. It can be above or below                |
| `leftClick`               | `boolean` | To set click event on which context menu will open. Its value can be true or false. If false then it will be right-clicked. If True then it will be left-clicked. |

## Example Configuration

Here's an example of how to configure the Context Menu component in your component's TypeScript file.

```typescript
import { Component } from '@angular/core';

// For Complete Library
import { inputContextData, TourGuideData } from '@uxpractice/ruc-lib/context-menu';

// For Individual package
import { inputContextData, TourGuideData } from '@ruc-lib/context-menu';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
})
export class AppComponent {
    inputContextData: inputContextData = {
        type: 'icon',
        matIconName: 'account_balance',
        matButtonColor: 'primary',
        matButtonLabelName: 'Click',
        imgUrl: 'abc.jpg',
        alternateImg: '',
        contextMenuData: [
            { label: 'Copy', icon: 'file_copy', id: 1, disabled: true },
            { label: 'Create', icon: 'create', id: 2, disabled: false },
            {
                label: 'Send to',
                icon: 'send',
                disabled: false,
                submenu: [
                    { label: 'Bluetooth', id: 3, icon: 'bluetooth', disabled: false },
                    { label: 'email', id: 4, icon: 'email', disabled: true },
                ],
            },
        ],
        xPosition: 'after',
        yPosition: 'below',
        leftClick: false,
    };

    passEvent(event: any) {
        console.log('Context Menu 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 Context Menu component. If you have any feedback or suggestions, please let us know!