@ruc-lib/drawer 2.0.0 → 3.1.0

package/README.md

@@ -1,136 +1,227 @@
 # ruclib-drawer
 
-This library provides a flexible and customizable drawer component for your Angular applications. Users can integrate the drawer component using Angular selectors with ease. Below are the features, usage instructions, and integration details:
-
-## RUC Library Installation Guide
-
-Users can easily install the RUC (Ruxptest Library) from npm. Additionally, they can also choose to install individual components based on their requirements.
+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 complete library
+### Install Individual Component
+If you only need the Drawer component:
+```bash
+npm install @ruc-lib/drawer
+```
 
-`npm install @uxpractice/ruc-lib`
+### 📦 Version Compatibility
 
-## Install individual component
+Please ensure you install the correct version of `@ruc-lib/drawer` based on your Angular version.
 
-If users only need the drawer component, they can install it separately
+| 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`     |
 
-`npm install @ruc-lib/drawer`
 
 ## Usage
 
-To use the drawer component in your project, follow the integration guidelines provided in the documentation. Customize the drawer as per your requirements by adjusting the configuration options.
-
-## Using Selector
-
-1.	Import `DrawerModule` into `app.module.ts` file. 
-`( import { RuclibDrawerModule } from '@ruc-lib/drawer'; OR import { RuclibDrawerModule } from '@ uxpractice /ruc-lib/drawer'; )`
-2.	Use the drawer selector in your HTML file.
-3.	Handle input and output bindings accordingly.
-
+### 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
+}
 ```
-<uxp-ruclib-drawer 
-    (rucEvent)="passEvent($event)" 
-    [rucInputData]="inputObjectDataDrawer" 
-    [customTheme]="customTheme">
-</uxp-ruclib-drawer>
-```
-
-# Input and Output
-
-## Input and Output
-
-Inputs:
-•	rucInputData: Data to be passed to the drawer.
-•	customTheme: Custom styling/theme for the drawer.
-
-Outputs:
-•	rucEvent: Event emitted from the drawer.
-
 
-## rucInputData configurations options- 
+### 2. Use the Component
+In your component's template, use the `<uxp-ruclib-drawer>` selector:
 
-```
-DrawerDefaultConfig {
-    drawerPosition: string = 'left',
-    mode: string =  'over',
-    initialOpenedState:  boolean = false,
-    drawerWidth: string = '250px',
-    drawerHeight: string = '',
-    content: {
-        drawerTitle: string = 'Drawer Title',
-        drawerBody: string = '<p>This is the <strong>body</strong> content of the drawer.</p><p>It can contain <em>HTML</em>.</p>',
-        mainBody: string = '<h2>Main Content Area</h2><p>This is where the main application content would go.</p>',
-    },
-    disableToggleButtonInMainContent:  boolean = false,
-    toggleButtonText: object = {
-        open: string =  'Open Drawer',
-        close: string = 'Close Drawer',
-    },
-    hasBackdrop:  boolean = true,
-    backdropBackgroundColor: string = 'rgba(129, 124, 124, 0.6)',
-    showCloseIcon:  boolean = true,
-    disableClose: boolean = false,
-    animationDuration: string = '300ms',
-    toggleButtonIcon: string = '',
-    toggleButtonImageAlt: string = '',
-    toggleButtonImageUrl: string = '',
-    toggleButtonDimensions: ButtonDimensions = {
-        width: string = 'auto',
-        height: string = '40px',
-        padding: string = '10px',
-        fontSize: string = '13px',
-        iconSize: string = '24px',
-    },
-    closeButtonDimensions: IconDimensions = {
-        width: string = '40px',
-        height: string = '40px',
-        iconSize: string = '24px',
-    },
-};
+```html
+<uxp-ruclib-drawer
+    [rucInputData]="drawerInput"
+    [customTheme]="customTheme"
+    (rucEvent)="passEvent($event)">
+</uxp-ruclib-drawer>
 ```
 
-# Default value be like –
-
-```
-export const mockDrawerInput = {
+## 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: '250px',
+    drawerWidth: '300px',
     drawerHeight: '',
     content: {
-        drawerTitle: 'Drawer Title',
-        drawerBody: '<p>This is the <strong>body</strong> content of the drawer.</p><p>It can contain <em>HTML</em>.</p>',
-        mainBody: '<h2>Main Content Area</h2><p>This is where the main application content would go.</p>',
+        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 Drawer',
-        close: 'Close Drawer',
+        open: 'Open Menu',
+        close: 'Close Menu',
     },
     hasBackdrop: true,
-    backdropBackgroundColor: 'rgba(129, 124, 124, 0.6)',
+    backdropBackgroundColor: 'rgba(0, 0, 0, 0.5)',
     showCloseIcon: true,
     disableClose: false,
-    animationDuration: '300ms',
-    toggleButtonIcon: '',
-    toggleButtonImageAlt: '',
+    animationDuration: '400ms',
+    toggleButtonIcon: 'menu',
     toggleButtonImageUrl: '',
     toggleButtonDimensions: {
         width: 'auto',
-        height: '40px',
-        padding: '10px',
-        fontSize: '13px',
+        height: '48px',
+        padding: '0 16px',
+        fontSize: '14px',
         iconSize: '24px',
     },
     closeButtonDimensions: {
-        width: '40px',
-        height: '40px',
+        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
 
@@ -138,4 +229,4 @@ Contributions are welcome! Feel free to open issues or pull requests for any enh
 
 # Acknowledgements
 
-Thank you for choosing the Drawer Component Library. If you have any feedback or suggestions, please let us know!
+Thank you for choosing the Drawer Component Library. If you have any feedback or suggestions, please let us know!