@ruc-lib/drawer 3.1.0 → 3.2.0

package/interface/drawer.d.ts

@@ -0,0 +1,203 @@
+import { MatDrawerMode } from "@angular/material/sidenav";
+import { Type } from "@angular/core";
+/**
+ * Defines the dimensions for a button, including text and icon sizing.
+ */
+export interface ButtonDimensions {
+    /**
+     * The width of the button.
+     * @example '120px', '5em'
+     * @optional
+     */
+    width?: string;
+    /**
+     * The height of the button.
+     * @example '40px', '2.5em'
+     * @optional
+     */
+    height?: string;
+    /**
+     * The padding of the button. Primarily for the main toggle button.
+     * @example '0 10px'
+     * @optional
+     */
+    padding?: string;
+    /**
+     * The font size for text within the button.
+     * @example '14px'
+     * @optional
+     */
+    fontSize?: string;
+    /**
+     * The size of the icon within the button.
+     * @example '20px'
+     * @optional
+     */
+    iconSize?: string;
+}
+/**
+ * Defines the dimensions for an icon button, like a close button.
+ */
+export interface IconDimensions {
+    /**
+     * The width of the icon button.
+     * @example '32px'
+     * @optional
+     */
+    width?: string;
+    /**
+     * The height of the icon button.
+     * @example '32px'
+     * @optional
+     */
+    height?: string;
+    /**
+     * The size of the icon itself within the button.
+     * @example '18px'
+     * @optional
+     */
+    iconSize?: string;
+}
+/**
+ * Defines the input properties for the RuclibDrawerComponent.
+ */
+export interface RuclibDrawerInput {
+    /**
+     * Position of the drawer.
+     * @default 'left'
+     * @optional
+     */
+    drawerPosition?: 'left' | 'right' | 'top' | 'bottom';
+    /**
+     * Mode of the drawer.
+     * `side`: Drawer stays open and reduces the content area.
+     * `over`: Drawer floats over the content.
+     * `push`: Drawer pushes the content away.
+     * @optional
+     */
+    mode?: MatDrawerMode;
+    /**
+     * Whether the drawer is initially opened.
+     * @optional
+     */
+    initialOpenedState?: boolean;
+    /**
+     * Width of the drawer, used when `drawerPosition` is 'left' or 'right'.
+     * @example '250px', '30vw'
+     * @optional
+     */
+    drawerWidth?: string;
+    /**
+     * Height of the drawer, used when `drawerPosition` is 'top' or 'bottom'.
+     * @example '200px', '40vh'
+     * @optional
+     */
+    drawerHeight?: string;
+    /**
+     * Content to be displayed in the drawer and main area.
+     * @optional
+     */
+    content?: {
+        /**
+         * Title displayed within the drawer.
+         * @optional
+         */
+        drawerTitle?: string;
+        /**
+         * HTML content for the body of the drawer. Used if `drawerContentComponent` is not provided.
+         * @optional
+         */
+        drawerBody?: string;
+        /**
+         * An Angular component to be rendered as the drawer's body content.
+         * If provided, `drawerBody` (HTML string) will be ignored for the drawer.
+         * @optional
+         */
+        drawerContentComponent?: Type<any>;
+        /**
+         * HTML content for the main application area beside/under the drawer.
+         * @optional
+         */
+        mainBody?: string;
+    };
+    /**
+     * Data to be passed to the `drawerContentComponent` instance.
+     * The dynamic component should have an @Input() property to receive this data.
+     */
+    drawerContentComponentData?: any;
+    /**
+     * Whether to disable the toggle button in the main content area.
+     * @optional
+     */
+    disableToggleButtonInMainContent?: boolean;
+    /**
+     * Text for the toggle button, supporting different text for open and close states.
+     * Also used for aria-label.
+     * @optional
+     */
+    toggleButtonText?: {
+        /**
+         * Text for the button when the drawer is closed (action to open).
+         * @optional
+         */
+        open?: string;
+        /**
+         * Text for the button when the drawer is open (action to close).
+         * @optional
+         */
+        close?: string;
+    };
+    /**
+     * Material icon name for the toggle button.
+     * @example 'menu', 'settings'
+     * @optional
+     */
+    toggleButtonIcon?: string;
+    /**
+     * URL for an image to be used in the toggle button.
+     * @optional
+     */
+    toggleButtonImageUrl?: string;
+    /**
+     * Alt text for the toggle button image.
+     * @optional
+     */
+    toggleButtonImageAlt?: string;
+    /**
+     * Whether the drawer has a backdrop, especially in 'over' mode.
+     * @optional
+     */
+    hasBackdrop?: boolean;
+    /**
+     * Custom background color for the backdrop.
+     * @example 'rgba(0,0,0,0.5)', '#333333'
+     * @optional
+     */
+    backdropBackgroundColor?: string;
+    /**
+     * Whether to show a close icon (e.g., 'x') inside the drawer.
+     * @optional
+     */
+    showCloseIcon?: boolean;
+    /**
+     * Whether to disable closing the drawer by pressing the Escape key or clicking on the backdrop.
+     * @optional
+     */
+    disableClose?: boolean;
+    /**
+     * Duration for the drawer's open/close animation.
+     * @example '300ms', '0.5s'
+     * @optional Defaults to Material's default (usually around 400ms for MatDrawer, or 300ms for custom animations).
+     */
+    animationDuration?: string;
+    /**
+     * Custom dimensions for the main toggle button.
+     * @optional
+     */
+    toggleButtonDimensions?: ButtonDimensions;
+    /**
+     * Custom dimensions for the close icon button inside the drawer.
+     * @optional
+     */
+    closeButtonDimensions?: IconDimensions;
+}

package/lib/ruclib-drawer/ruclib-drawer.component.d.ts

@@ -0,0 +1,176 @@
+import { OnInit, OnChanges, SimpleChanges, EventEmitter, AfterViewInit, ChangeDetectorRef, ViewContainerRef, OnDestroy } from '@angular/core';
+import { AnimationEvent } from '@angular/animations';
+import { MatDrawerMode } from '@angular/material/sidenav';
+import { RuclibDrawerInput } from '../../interface/drawer';
+import * as i0 from "@angular/core";
+/**
+ * @Component RuclibDrawerComponent
+ * @description A highly configurable drawer component that can slide in from any of the four directions (left, right, top, bottom).
+ * It uses custom Angular animations for smooth transitions and supports theming.
+ */
+export declare class RuclibDrawerComponent implements OnInit, OnChanges, AfterViewInit, OnDestroy {
+    private cdr;
+    /**
+     * Input data for configuring the drawer's appearance and behavior.
+     * @see RuclibDrawerInput interface for detailed properties.
+     */
+    rucInputData: RuclibDrawerInput;
+    /**
+     * Optional custom theme class to be applied to the drawer panel.
+     * @example 'dark-theme', 'custom-theme-one'
+     */
+    customTheme: string | undefined;
+    /**
+     * EventEmitter for various drawer events.
+     * Emits objects with `type` (e.g., 'openedStart', 'closedStart', 'openedChange', 'drawerToggle')
+     * and `opened` (boolean) and `position` (string) properties.
+     */
+    rucEvent: EventEmitter<any>;
+    /** ViewContainerRef to host the dynamically loaded component. */
+    drawerComponentHost: ViewContainerRef;
+    /** Reference to the dynamically created component. */
+    private dynamicComponentRef;
+    /**
+     * Current animation state of the drawer ('in' or 'out').
+     * @public
+     */
+    drawerAnimationState: 'in' | 'out';
+    /**
+     * Current active position of the drawer.
+     * @public
+     * @default 'left'
+     */
+    currentDrawerPosition: 'left' | 'right' | 'top' | 'bottom';
+    /**
+     * Stores the next position if the drawer is currently open and a new position is requested.
+     * Used to sequence close and open animations.
+     * @private
+     */
+    private pendingDrawerPosition;
+    /**
+     * Flag to indicate if an animation is currently in progress to prevent rapid toggling.
+     * @public
+     */
+    isAnimating: boolean;
+    /**
+     * Effective animation duration for the drawer, derived from input or default.
+     * @public
+     * @default '300ms'
+     */
+    effectiveAnimationDuration: string;
+    /**
+     * Mode of the drawer, primarily for determining backdrop behavior with custom animations.
+     * @public
+     * @default 'side'
+     */
+    matDrawerMode: MatDrawerMode;
+    /**
+     * Actual position ('start' or 'end') used by Angular Material's MatDrawer if it were directly used.
+     * Retained for logical consistency in determining layout.
+     * @public
+     * @default 'start'
+     */
+    matActualPosition: 'start' | 'end';
+    /**
+     * Flag indicating if the drawer is in a vertical layout (top/bottom).
+     * Helps determine if width or height should be 100%.
+     * @public
+     */
+    isVerticalLayout: boolean;
+    /**
+     * Effective dimension (width or height) of the drawer panel.
+     * @public
+     * @default '250px'
+     */
+    effectiveDrawerDimension: string;
+    constructor(cdr: ChangeDetectorRef);
+    /**
+     * Angular lifecycle hook that is called after data-bound properties of a directive are initialized.
+     */
+    ngOnInit(): void;
+    /**
+     * Angular lifecycle hook that is called after Angular has fully initialized a component's view.
+     */
+    ngAfterViewInit(): void;
+    /**
+     * Angular lifecycle hook that is called when any data-bound property of a directive changes.
+     * @param changes - Object containing the changed properties.
+     */
+    ngOnChanges(changes: SimpleChanges): void;
+    /**
+     * Applies input data to component properties, calculating dimensions and positions.
+     * @private
+     */
+    private applyInputs;
+    /**
+     * Toggles the drawer's open/close state or switches to a new position.
+     * @param requestedPosition - The desired position to open the drawer from. If not provided, uses `currentDrawerPosition`.
+     */
+    toggleDrawer(requestedPosition?: 'left' | 'right' | 'top' | 'bottom'): void;
+    /**
+     * Sets the drawer's open state and triggers the animation.
+     * @param open - Boolean indicating whether to open (true) or close (false) the drawer.
+     * @private
+     */
+    private setDrawerOpenState;
+    /**
+     * Callback for when a drawer animation finishes.
+     * Manages state transitions, especially when switching between open drawers.
+     * @param event - The Angular AnimationEvent.
+     */
+    onAnimationDone(event: AnimationEvent): void;
+    /**
+     * Loads the dynamic component into the drawer if specified in rucInputData.
+     * Clears existing dynamic component if any.
+     * @private
+     */
+    private loadDynamicContent;
+    /**
+     * Getter for the current animation parameters to be passed to the animation triggers in the template.
+     * Includes the current animation state ('in' or 'out') and the effective duration.
+     */
+    get animationParams(): {
+        value: "out" | "in";
+        params: {
+            duration: string;
+        };
+    };
+    /**
+     * Getter for the backdrop animation parameters.
+     * Typically uses a faster duration than the main drawer animation.
+     */
+    get backdropAnimationParams(): {
+        value: "out" | "in";
+        params: {
+            duration: string;
+        };
+    };
+    /**
+     * Generates an accessible label for the toggle button based on the drawer's state and position.
+     * @returns The ARIA label string for the toggle button.
+     */
+    getToggleButtonAriaLabel(): string;
+    /**
+     * Handles clicks on the backdrop.
+     * Closes the drawer only if `disableClose` is not true.
+     * @public
+     */
+    handleBackdropClick(): void;
+    /**
+     * Listens for Escape key presses on the document.
+     * Closes the drawer if it's open and `disableClose` is not true.
+     * @param event - The KeyboardEvent.
+     */
+    onKeydownHandler(event: KeyboardEvent): void;
+    /**
+     * Clears any dynamically loaded component.
+     * @private
+     */
+    private clearDynamicContent;
+    /**
+     * Angular lifecycle hook that is called clear dynamic component content.
+     */
+    ngOnDestroy(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<RuclibDrawerComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<RuclibDrawerComponent, "uxp-ruclib-drawer", never, { "rucInputData": "rucInputData"; "customTheme": "customTheme"; }, { "rucEvent": "rucEvent"; }, never, never, false, never>;
+}

package/lib/ruclib-drawer.module.d.ts

@@ -0,0 +1,13 @@
+import * as i0 from "@angular/core";
+import * as i1 from "./ruclib-drawer/ruclib-drawer.component";
+import * as i2 from "../pipes/pipes/safe-html.pipe";
+import * as i3 from "@angular/common";
+import * as i4 from "@angular/material/button";
+import * as i5 from "@angular/material/icon";
+import * as i6 from "@angular/material/sidenav";
+import * as i7 from "@angular/material/toolbar";
+export declare class RuclibDrawerModule {
+    static ɵfac: i0.ɵɵFactoryDeclaration<RuclibDrawerModule, never>;
+    static ɵmod: i0.ɵɵNgModuleDeclaration<RuclibDrawerModule, [typeof i1.RuclibDrawerComponent, typeof i2.SafeHtmlPipe], [typeof i3.CommonModule, typeof i4.MatButtonModule, typeof i5.MatIconModule, typeof i6.MatSidenavModule, typeof i7.MatToolbarModule], [typeof i1.RuclibDrawerComponent]>;
+    static ɵinj: i0.ɵɵInjectorDeclaration<RuclibDrawerModule>;
+}

package/model/default-values.d.ts

@@ -0,0 +1,2 @@
+import { RuclibDrawerInput } from "../interface/drawer";
+export declare const defaultValues: RuclibDrawerInput;

package/package.json

@@ -1,16 +1,24 @@
 {
   "name": "@ruc-lib/drawer",
-  "version": "3.1.0",
+  "version": "3.2.0",
+  "license": "MIT",
   "peerDependencies": {
-    "@angular/common": "^15.0.0 || ^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^20.0.0",
-    "@angular/core": "^15.0.0 || ^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^20.0.0",
-    "@angular/material": "^15.0.0 || ^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^20.0.0"
+    "@angular/common": "^17.0.0 || ^16.0.0 || ^15.0.0",
+    "@angular/core": "^17.0.0 || ^16.0.0 || ^15.0.0",
+    "@angular/material": "^15.2.9 || ^14.0.0 || ^13.0.0"
   },
   "dependencies": {
     "tslib": "^2.3.0"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "sideEffects": false,
-  "module": "fesm2022/ruc-lib-drawer.mjs",
+  "module": "fesm2015/ruc-lib-drawer.mjs",
+  "es2020": "fesm2020/ruc-lib-drawer.mjs",
+  "esm2020": "esm2020/ruc-lib-drawer.mjs",
+  "fesm2020": "fesm2020/ruc-lib-drawer.mjs",
+  "fesm2015": "fesm2015/ruc-lib-drawer.mjs",
   "typings": "index.d.ts",
   "exports": {
     "./package.json": {
@@ -18,7 +26,11 @@
     },
     ".": {
       "types": "./index.d.ts",
-      "default": "./fesm2022/ruc-lib-drawer.mjs"
+      "esm2020": "./esm2020/ruc-lib-drawer.mjs",
+      "es2020": "./fesm2020/ruc-lib-drawer.mjs",
+      "es2015": "./fesm2015/ruc-lib-drawer.mjs",
+      "node": "./fesm2015/ruc-lib-drawer.mjs",
+      "default": "./fesm2020/ruc-lib-drawer.mjs"
     }
   }
 }

package/pipes/pipes/safe-html.pipe.d.ts

@@ -0,0 +1,24 @@
+import { PipeTransform } from '@angular/core';
+import { DomSanitizer } from '@angular/platform-browser';
+import * as i0 from "@angular/core";
+/**
+ * @Pipe SafeHtmlPipe
+ * @name safeHtml
+ * @description A pipe that bypasses Angular's built-in security and sanitizes HTML content,
+ * allowing it to be safely rendered in the DOM. Use with caution and only with trusted HTML sources.
+ */
+export declare class SafeHtmlPipe implements PipeTransform {
+    private sanitizer;
+    /**
+     * @param sanitizer - An instance of DomSanitizer used to bypass security.
+     */
+    constructor(sanitizer: DomSanitizer);
+    /**
+     * Transforms a string containing HTML into a SafeHtml object that can be bound to [innerHTML].
+     * @param value - The HTML string to sanitize.
+     * @returns A SafeHtml object, which Angular trusts as safe HTML.
+     */
+    transform(value: any): any;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SafeHtmlPipe, never>;
+    static ɵpipe: i0.ɵɵPipeDeclaration<SafeHtmlPipe, "safeHtml", false>;
+}