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

npm install @uxpractice/ruc-lib

Install Individual Component

If you only need the Drawer component:

npm install @ruc-lib/drawer

📦 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.0.0 | | 16.x.x | npm install @ruc-lib/drawer@^3.0.0 |

Usage

1. Import the Component

In your Angular component file (e.g., app.component.ts), import the RuclibDrawerComponent:

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:

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

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:

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