npm package: @ruc-lib/drawer
Description: A highly configurable drawer component that provides a slide-in panel from any of the four directions (left, right, top, or bottom). It's designed for displaying supplementary content, navigation, or forms without navigating away from the current view.
Latest version: 4.0.0

# ruclib-drawer

A highly configurable drawer component that provides a slide-in panel from any of the four directions (left, right, top, or bottom). It's designed for displaying supplementary content, navigation, or forms without navigating away from the current view.

## Features

- **Flexible Positioning**: Open the drawer from the 'left', 'right', 'top', or 'bottom' of the container.
- **Custom Sizing**: Define custom width for vertical drawers and height for horizontal drawers.
- **Smooth Animations**: Configurable slide-in/out animation duration.
- **Display Modes**: Supports an 'over' mode where the drawer slides over the main content.
- **Content Customization**: Set a custom title and use rich HTML for the drawer's body and the main content area.
- **Interactive Toggle**:
  - Optionally display a toggle button in the main content area.
  - Customize button text for 'open' and 'close' states.
  - Use Material icons or custom image URLs for the button.
- **Backdrop Control**: Enable or disable a backdrop, and customize its background color.
- **Close Mechanisms**:
  - Show or hide a close icon within the drawer.
  - Prevent closing via the Escape key or backdrop click.
- **Theming**: Apply custom theme classes for tailored styling.

## Installation Guide

### Install the Entire Library
```bash
npm install @uxpractice/ruc-lib
```

### Install Individual Component

If you only need the Drawer component:

**For Angular 15:**
```bash
npm install @ruc-lib/drawer@3.2.0 @angular/material@^15.0.0 @angular/cdk@^15.0.0
```

**For Angular 16:**
```bash
npm install @ruc-lib/drawer@3.2.0 @angular/material@^16.0.0 @angular/cdk@^16.0.0
```

**For Angular 17:**
```bash
npm install @ruc-lib/drawer@4.0.0 @angular/material@^17.0.0 @angular/cdk@^17.0.0
```

**For Angular 18:**
```bash
npm install @ruc-lib/drawer@4.0.0 @angular/material@^18.0.0 @angular/cdk@^18.0.0
```

**For Angular 19:**
```bash
npm install @ruc-lib/drawer@4.0.0 @angular/material@^19.0.0 @angular/cdk@^19.0.0
```

**For Angular 20:**
```bash
npm install @ruc-lib/drawer@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/drawer` based on your Angular version.

| Angular Version    | Compatible `@ruc-lib/drawer` Version     |
|--------------------|------------------------------------------|
| 15.x.x             | `npm install @ruc-lib/drawer@^3.2.0`     |
| 16.x.x             | `npm install @ruc-lib/drawer@^3.2.0`     |
| 17.x.x             | `npm install @ruc-lib/drawer@^4.0.0`     |
| 18.x.x             | `npm install @ruc-lib/drawer@^4.0.0`     |
| 19.x.x             | `npm install @ruc-lib/drawer@^4.0.0`     |
| 20.x.x             | `npm install @ruc-lib/drawer@^4.0.0`     |


## Usage

### 1. Import the Component
In your Angular component file (e.g., `app.component.ts`), import the `RuclibDrawerComponent`:

```typescript
import { Component } from '@angular/core';

// For Complete Library
import { RuclibDrawerComponent } from '@uxpractice/ruc-lib/drawer';

// For Individual Package
import { RuclibDrawerComponent } from '@ruc-lib/drawer';

@Component({
  selector: 'app-root',
  imports: [RuclibDrawerComponent],
  templateUrl: './app.component.html',
})
export class AppComponent {
  // Component code here
}
```

### 2. Use the Component
In your component's template, use the `<uxp-ruclib-drawer>` selector:

```html
<uxp-ruclib-drawer
    [rucInputData]="drawerInput"
    [customTheme]="customTheme"
    (rucEvent)="passEvent($event)">
</uxp-ruclib-drawer>
```

## API Reference

### Component Inputs

| Input          | Type                  | Description                                      |
|----------------|-----------------------|--------------------------------------------------|
| `rucInputData` | `RuclibDrawerInput` | The main configuration object for the drawer.    |
| `customTheme`  | `string`              | An optional CSS class for custom theming.        |

### Component Outputs

| Output     | Type  | Description                                  |
|------------|-------|----------------------------------------------|
| `rucEvent` | `any` | Emits events from the drawer.                |

### `rucInputData` (`RuclibDrawerInput`)
This is the main configuration object for the Drawer component.

| Property                           | Type                 | Description                                                                                             |
|------------------------------------|----------------------|---------------------------------------------------------------------------------------------------------|
| `drawerPosition`                   | `string`             | Position of the drawer. Can be `'left'`, `'right'`, `'top'`, or `'bottom'`. Default is `'left'`.         |
| `mode`                             | `string`             | Drawer mode. Can be `'over'`, `'push'`, or `'side'`. Default is `'over'`.                               |
| `initialOpenedState`               | `boolean`            | If `true`, the drawer is open initially. Default is `false`.                                            |
| `drawerWidth`                      | `string`             | Width of the drawer when `drawerPosition` is `'left'` or `'right'`. Default is `'250px'`.               |
| `drawerHeight`                     | `string`             | Height of the drawer when `drawerPosition` is `'top'` or `'bottom'`.                                    |
| `content`                          | `object`             | An object containing the HTML content for the drawer and main area. See `Content` table below.          |
| `disableToggleButtonInMainContent` | `boolean`            | If `true`, the toggle button in the main content area is hidden. Default is `false`.                    |
| `toggleButtonText`                 | `object`             | An object for the toggle button's text. See `ToggleButtonText` table below.                             |
| `hasBackdrop`                      | `boolean`            | If `true`, a backdrop is shown when the drawer is open. Default is `true`.                              |
| `backdropBackgroundColor`          | `string`             | The CSS background color for the backdrop. Default is `'rgba(129, 124, 124, 0.6)'`.                     |
| `showCloseIcon`                    | `boolean`            | If `true`, a close icon is displayed inside the drawer. Default is `true`.                              |
| `disableClose`                     | `boolean`            | If `true`, the drawer cannot be closed by pressing Escape or clicking the backdrop. Default is `false`. |
| `animationDuration`                | `string`             | The duration of the open/close animation. Default is `'300ms'`.                                         |
| `toggleButtonIcon`                 | `string`             | The name of the Material Icon for the toggle button.                                                    |
| `toggleButtonImageUrl`             | `string`             | The URL for a custom image on the toggle button.                                                        |
| `toggleButtonDimensions`           | `ButtonDimensions`   | An object to control the dimensions of the toggle button. See `ButtonDimensions` table below.           |
| `closeButtonDimensions`            | `IconDimensions`     | An object to control the dimensions of the close icon. See `IconDimensions` table below.                |

### `content`
| Property      | Type     | Description                               |
|---------------|----------|-------------------------------------------|
| `drawerTitle` | `string` | The title displayed in the drawer's header. |
| `drawerBody`  | `string` | The HTML content for the drawer's body.   |
| `mainBody`    | `string` | The HTML content for the main area.       |

### `toggleButtonText`
| Property | Type     | Description                                 |
|----------|----------|---------------------------------------------|
| `open`   | `string` | Text for the toggle button to open the drawer. |
| `close`  | `string` | Text for the toggle button to close the drawer. |

### `toggleButtonDimensions` (`ButtonDimensions`)
| Property   | Type     | Description                               |
|------------|----------|-------------------------------------------|
| `width`    | `string` | The width of the toggle button.           |
| `height`   | `string` | The height of the toggle button.          |
| `padding`  | `string` | The padding of the toggle button.         |
| `fontSize` | `string` | The font size of the toggle button text.  |
| `iconSize` | `string` | The size of the icon on the toggle button. |

### `closeButtonDimensions` (`IconDimensions`)
| Property   | Type     | Description                      |
|------------|----------|----------------------------------|
| `width`    | `string` | The width of the close button.   |
| `height`   | `string` | The height of the close button.  |
| `iconSize` | `string` | The size of the close icon.      |

## Example Configuration

Here's an example of how to configure the Drawer component in your component's TypeScript file.

```typescript
import { Component } from '@angular/core';

// For Complete Library
import { RuclibDrawerModule, RuclibDrawerInput, ButtonDimensions, IconDimensions } from '@uxpractice/ruc-lib/drawer';

// For Individual package
import { RuclibDrawerModule, RuclibDrawerInput, ButtonDimensions, IconDimensions } from '@ruc-lib/drawer';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
})
export class AppComponent {
  customTheme = 'ruc-custom-theme';

  drawerInput: RuclibDrawerInput = {
    drawerPosition: 'left',
    mode: 'over',
    initialOpenedState: false,
    drawerWidth: '300px',
    drawerHeight: '',
    content: {
        drawerTitle: 'Navigation Menu',
        drawerBody: '<p>This is where your navigation links or filters would go.</p>',
        mainBody: '<h2>Main Application Content</h2><p>Click the button to open the drawer.</p>',
    },
    disableToggleButtonInMainContent: false,
    toggleButtonText: {
        open: 'Open Menu',
        close: 'Close Menu',
    },
    hasBackdrop: true,
    backdropBackgroundColor: 'rgba(0, 0, 0, 0.5)',
    showCloseIcon: true,
    disableClose: false,
    animationDuration: '400ms',
    toggleButtonIcon: 'menu',
    toggleButtonImageUrl: '',
    toggleButtonDimensions: {
        width: 'auto',
        height: '48px',
        padding: '0 16px',
        fontSize: '14px',
        iconSize: '24px',
    },
    closeButtonDimensions: {
        width: '48px',
        height: '48px',
        iconSize: '24px',
    },
  };

  passEvent(event: any) {
    console.log('Drawer 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 Drawer Component Library. If you have any feedback or suggestions, please let us know!