feat(Drawer): add new bq-drawer component

packages/beeq/.storybook/preview.ts

@@ -13,7 +13,7 @@ const withThemeProvider: DecoratorFunction<WebComponentsRenderer, { [x: string]:
     globals: { theme, mode },
   } = context;
   const body = document.querySelector('body.sb-show-main');
-  if (!body) return storyFn();
+  if (!(body instanceof HTMLElement)) return storyFn();
 
   body.setAttribute('bq-theme', (theme || 'BEEQ').toLowerCase());
   body.setAttribute('bq-mode', (mode || 'Light').toLowerCase());

packages/beeq/src/components.d.ts

@@ -13,6 +13,7 @@ import { TButtonAppearance, TButtonBorderRadius, TButtonSize, TButtonType, TButt
 import { TCardBorderRadius, TCardType } from "./components/card/bq-card.types";
 import { TDialogBorderRadius, TDialogFooterAppearance, TDialogSize } from "./components/dialog/bq-dialog.types";
 import { TDividerOrientation, TDividerStrokeLinecap, TDividerTitleAlignment } from "./components/divider/bq-divider.types";
+import { TDrawerPlacement } from "./components/drawer/bq-drawer.types";
 import { FloatingUIPlacement } from "./services/interfaces";
 import { TEmptyStateSize } from "./components/empty-state/bq-empty-state.types";
 import { TIconWeight } from "./components/icon/bq-icon.types";
@@ -38,6 +39,7 @@ export { TButtonAppearance, TButtonBorderRadius, TButtonSize, TButtonType, TButt
 export { TCardBorderRadius, TCardType } from "./components/card/bq-card.types";
 export { TDialogBorderRadius, TDialogFooterAppearance, TDialogSize } from "./components/dialog/bq-dialog.types";
 export { TDividerOrientation, TDividerStrokeLinecap, TDividerTitleAlignment } from "./components/divider/bq-divider.types";
+export { TDrawerPlacement } from "./components/drawer/bq-drawer.types";
 export { FloatingUIPlacement } from "./services/interfaces";
 export { TEmptyStateSize } from "./components/empty-state/bq-empty-state.types";
 export { TIconWeight } from "./components/icon/bq-icon.types";
@@ -399,6 +401,36 @@ export namespace Components {
          */
         "titleAlignment"?: TDividerTitleAlignment;
     }
+    interface BqDrawer {
+        /**
+          * If true, the drawer will not close when clicking outside the panel
+         */
+        "closeOnClickOutside": boolean;
+        /**
+          * If true, the dialog will not close when the [Esc] key is pressed
+         */
+        "closeOnEsc": boolean;
+        /**
+          * If true, the backdrop overlay will be shown when the drawer opens
+         */
+        "enableBackdrop": boolean;
+        /**
+          * Method to be called to hide the drawer component
+         */
+        "hide": () => Promise<void>;
+        /**
+          * If true, the drawer component will be shown
+         */
+        "open": boolean;
+        /**
+          * Defines the position of the drawer
+         */
+        "placement": TDrawerPlacement;
+        /**
+          * Method to be called to show the drawer component
+         */
+        "show": () => Promise<void>;
+    }
     interface BqDropdown {
         /**
           * If true, the dropdown panel will be visible and won't be shown.
@@ -1272,6 +1304,10 @@ export interface BqDialogCustomEvent<T> extends CustomEvent<T> {
     detail: T;
     target: HTMLBqDialogElement;
 }
+export interface BqDrawerCustomEvent<T> extends CustomEvent<T> {
+    detail: T;
+    target: HTMLBqDrawerElement;
+}
 export interface BqDropdownCustomEvent<T> extends CustomEvent<T> {
     detail: T;
     target: HTMLBqDropdownElement;
@@ -1518,6 +1554,26 @@ declare global {
         prototype: HTMLBqDividerElement;
         new (): HTMLBqDividerElement;
     };
+    interface HTMLBqDrawerElementEventMap {
+        "bqClose": any;
+        "bqOpen": any;
+        "bqAfterOpen": any;
+        "bqAfterClose": any;
+    }
+    interface HTMLBqDrawerElement extends Components.BqDrawer, HTMLStencilElement {
+        addEventListener<K extends keyof HTMLBqDrawerElementEventMap>(type: K, listener: (this: HTMLBqDrawerElement, ev: BqDrawerCustomEvent<HTMLBqDrawerElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLBqDrawerElementEventMap>(type: K, listener: (this: HTMLBqDrawerElement, ev: BqDrawerCustomEvent<HTMLBqDrawerElementEventMap[K]>) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+    }
+    var HTMLBqDrawerElement: {
+        prototype: HTMLBqDrawerElement;
+        new (): HTMLBqDrawerElement;
+    };
     interface HTMLBqDropdownElementEventMap {
         "bqOpen": { open: boolean };
     }
@@ -1941,6 +1997,7 @@ declare global {
         "bq-checkbox": HTMLBqCheckboxElement;
         "bq-dialog": HTMLBqDialogElement;
         "bq-divider": HTMLBqDividerElement;
+        "bq-drawer": HTMLBqDrawerElement;
         "bq-dropdown": HTMLBqDropdownElement;
         "bq-empty-state": HTMLBqEmptyStateElement;
         "bq-icon": HTMLBqIconElement;
@@ -2377,6 +2434,44 @@ declare namespace LocalJSX {
          */
         "titleAlignment"?: TDividerTitleAlignment;
     }
+    interface BqDrawer {
+        /**
+          * If true, the drawer will not close when clicking outside the panel
+         */
+        "closeOnClickOutside"?: boolean;
+        /**
+          * If true, the dialog will not close when the [Esc] key is pressed
+         */
+        "closeOnEsc"?: boolean;
+        /**
+          * If true, the backdrop overlay will be shown when the drawer opens
+         */
+        "enableBackdrop"?: boolean;
+        /**
+          * Callback handler to be called after the drawer has been closed
+         */
+        "onBqAfterClose"?: (event: BqDrawerCustomEvent<any>) => void;
+        /**
+          * Callback handler to be called after the drawer has been opened
+         */
+        "onBqAfterOpen"?: (event: BqDrawerCustomEvent<any>) => void;
+        /**
+          * Callback handler to be called when the drawer is closed
+         */
+        "onBqClose"?: (event: BqDrawerCustomEvent<any>) => void;
+        /**
+          * Callback handler to be called when the drawer is opened
+         */
+        "onBqOpen"?: (event: BqDrawerCustomEvent<any>) => void;
+        /**
+          * If true, the drawer component will be shown
+         */
+        "open"?: boolean;
+        /**
+          * Defines the position of the drawer
+         */
+        "placement"?: TDrawerPlacement;
+    }
     interface BqDropdown {
         /**
           * If true, the dropdown panel will be visible and won't be shown.
@@ -3357,6 +3452,7 @@ declare namespace LocalJSX {
         "bq-checkbox": BqCheckbox;
         "bq-dialog": BqDialog;
         "bq-divider": BqDivider;
+        "bq-drawer": BqDrawer;
         "bq-dropdown": BqDropdown;
         "bq-empty-state": BqEmptyState;
         "bq-icon": BqIcon;
@@ -3404,6 +3500,7 @@ declare module "@stencil/core" {
             "bq-checkbox": LocalJSX.BqCheckbox & JSXBase.HTMLAttributes<HTMLBqCheckboxElement>;
             "bq-dialog": LocalJSX.BqDialog & JSXBase.HTMLAttributes<HTMLBqDialogElement>;
             "bq-divider": LocalJSX.BqDivider & JSXBase.HTMLAttributes<HTMLBqDividerElement>;
+            "bq-drawer": LocalJSX.BqDrawer & JSXBase.HTMLAttributes<HTMLBqDrawerElement>;
             "bq-dropdown": LocalJSX.BqDropdown & JSXBase.HTMLAttributes<HTMLBqDropdownElement>;
             "bq-empty-state": LocalJSX.BqEmptyState & JSXBase.HTMLAttributes<HTMLBqEmptyStateElement>;
             /**

packages/beeq/src/components/alert/scss/bq-alert.scss

@@ -77,7 +77,7 @@
 }
 
 /**
- * Tweak the close bq-buton styles so it remain small wihout extra padding
+ * Tweak the close bq-button styles so it remain small without extra padding
  */
 .bq-alert__close::part(button) {
   @apply h-fit rounded-s border-0 p-0;

packages/beeq/src/components/button/readme.md

@@ -52,6 +52,7 @@ Buttons are designed for users to take action on a page or a screen.
 
  - [bq-alert](../alert)
  - [bq-dialog](../dialog)
+ - [bq-drawer](../drawer)
  - [bq-input](../input)
  - [bq-notification](../notification)
  - [bq-select](../select)
@@ -67,6 +68,7 @@ graph TD;
   bq-button --> bq-icon
   bq-alert --> bq-button
   bq-dialog --> bq-button
+  bq-drawer --> bq-button
   bq-input --> bq-button
   bq-notification --> bq-button
   bq-select --> bq-button

packages/beeq/src/components/dialog/_storybook/bq-dialog.mdx

@@ -4,7 +4,7 @@ import { ArgTypes, Title, Subtitle } from '@storybook/addon-docs';
   <div className="bq-doc__container" >
     <Title>Dialog</Title>
 
-    Description A Dialog is a UI component used to display additional content or prompt a user for action.
+    A Dialog is a UI component used to display additional content or prompt a user for action.
     It provides a way to display additional information, options, or controls in a separate, non-obstructive interface element.
 
     <Subtitle>Usage</Subtitle>

packages/beeq/src/components/divider/readme.md

@@ -33,11 +33,13 @@
 
 ### Used by
 
+ - [bq-drawer](../drawer)
  - [bq-steps](../steps)
 
 ### Graph
 ```mermaid
 graph TD;
+  bq-drawer --> bq-divider
   bq-steps --> bq-divider
   style bq-divider fill:#f9f,stroke:#333,stroke-width:4px
 ```

packages/beeq/src/components/drawer/__tests__/bq-drawer.e2e.ts

@@ -0,0 +1,144 @@
+import { newE2EPage } from '@stencil/core/testing';
+
+describe('bq-drawer', () => {
+  it('should render', async () => {
+    const page = await newE2EPage({
+      html: '<bq-drawer></bq-drawer>',
+    });
+    const element = await page.find('bq-drawer');
+
+    expect(element).toHaveClass('hydrated');
+  });
+
+  it('should have shadow root', async () => {
+    const page = await newE2EPage({
+      html: '<bq-drawer></bq-drawer>',
+    });
+    const element = await page.find('bq-drawer');
+
+    expect(element.shadowRoot).not.toBeNull();
+  });
+
+  it('should render as hidden', async () => {
+    const page = await newE2EPage({
+      html: `<bq-drawer></bq-drawer>`,
+    });
+
+    const element = await page.find('bq-drawer >>> [part="panel"]');
+    expect(element).toEqualAttribute('aria-hidden', 'true');
+  });
+
+  it('should render as hidden with `open="false"`', async () => {
+    const page = await newE2EPage({
+      html: `<bq-drawer open="false"></bq-drawer>`,
+    });
+
+    const element = await page.find('bq-drawer >>> [part="panel"]');
+    expect(element).toEqualAttribute('aria-hidden', 'true');
+  });
+
+  it('should render as open', async () => {
+    const page = await newE2EPage({
+      html: `<bq-drawer open></bq-drawer>`,
+    });
+
+    const element = await page.find('bq-drawer >>> [part="panel"]');
+    expect(element).toEqualAttribute('aria-hidden', 'false');
+    expect(element).not.toHaveClass('hidden');
+  });
+
+  it('should render as open with `open="true"`', async () => {
+    const page = await newE2EPage({
+      html: `<bq-drawer open="true"></bq-drawer>`,
+    });
+
+    const element = await page.find('bq-drawer >>> [part="panel"]');
+    expect(element).toEqualAttribute('aria-hidden', 'false');
+    expect(element).not.toHaveClass('hidden');
+  });
+
+  it('should display drawer title', async () => {
+    const page = await newE2EPage({
+      html: `
+        <bq-drawer>
+          <div slot="title">Drawer Title</div>
+        </bq-drawer>
+      `,
+    });
+
+    const element = await page.find('bq-drawer');
+    expect(element).toEqualText('Drawer Title');
+  });
+
+  it('should render basic body drawer slot', async () => {
+    const page = await newE2EPage({
+      html: `
+        <bq-drawer>
+          <div slot>Slot</div>
+        </bq-drawer>
+      `,
+    });
+
+    const description = await page.find('bq-drawer >>> slot');
+    expect(description).not.toBeNull();
+  });
+
+  it('should render footer drawer slot', async () => {
+    const page = await newE2EPage({
+      html: `
+        <bq-drawer>
+          <div slot="footer">Footer slot</div>
+        </bq-drawer>
+      `,
+    });
+
+    const description = await page.find('bq-drawer >>> slot[name="footer"]');
+    expect(description).not.toBeNull();
+  });
+
+  it('should call `show` method', async () => {
+    const page = await newE2EPage({
+      html: `
+        <bq-drawer>
+          <div slot="title">Drawer Title</div>
+        </bq-drawer>
+      `,
+    });
+
+    const closedDrawer = await page.find('bq-drawer >>> [part="panel"]');
+    expect(closedDrawer.getAttribute('aria-hidden')).toBe('true');
+    expect(closedDrawer).toHaveAttribute('hidden');
+
+    await page.$eval('bq-drawer', async (elem: HTMLBqDrawerElement) => {
+      await elem.show();
+    });
+    await page.waitForChanges();
+
+    const openDrawer = await page.find('bq-drawer >>> [part="panel"]');
+    expect(openDrawer.getAttribute('aria-hidden')).toBe('false');
+    expect(openDrawer).not.toHaveAttribute('hidden');
+  });
+
+  it('should call `hide` method', async () => {
+    const page = await newE2EPage({
+      html: `
+        <bq-drawer open>
+          <div slot="title">Drawer Title</div>
+        </bq-drawer>
+      `,
+    });
+
+    const openDrawer = await page.find('bq-drawer >>> [part="panel"]');
+    expect(openDrawer.getAttribute('aria-hidden')).toBe('false');
+    expect(openDrawer).not.toHaveAttribute('hidden');
+
+    await page.$eval('bq-drawer', async (elem: HTMLBqDrawerElement) => {
+      await elem.hide();
+    });
+    await page.waitForChanges();
+
+    const closedDrawer = await page.find('bq-drawer >>> [part="panel"]');
+    expect(closedDrawer.getAttribute('aria-hidden')).toBe('true');
+    expect(closedDrawer).toHaveAttribute('hidden');
+  });
+});

packages/beeq/src/components/drawer/_storybook/bq-drawer.mdx

@@ -0,0 +1,30 @@
+import { ArgTypes, Title, Subtitle } from '@storybook/addon-docs';
+
+<div className="bq-doc__wrapper" data-theme="light">
+  <div className="bq-doc__container">
+    <Title>Drawer</Title>
+
+    A Drawer is a UI component that provides a sliding panel interface commonly used for navigation or presenting
+    additional content without taking up significant screen space.
+
+    <Subtitle>Usage</Subtitle>
+
+    - Navigation: Drawers are commonly used for housing navigation menus or sidebar menus. They can be toggled open
+    and closed to provide easy access to navigation links.
+    - Additional content: This component can also be used to display additional content or options that are not always visible on the screen.
+    This allows to access exatra functionality without cluttering the main interface.
+
+    <Subtitle>👍 When to use</Subtitle>
+
+    Utilize the Drawer component for various scenarios such as sidebar navigation, user preferences display, and mobile menu implementation,
+    offering compact access to application sections, settings, and navigation options.
+
+    - Limited screen space: When screen real estate is limited, such as on mobile devices or smaller viewports, drawers can provide a compact way to present additional content.
+    - Contextual information: Use drawers to display contextual information or actions related to the current screen or user interaction. 
+    - Multi-level Navigation: Drawers are suitable for multi-level navigation structures, where sub-menus or nested content can be displayed hierarchically.
+
+    <Title>Properties</Title>
+
+    <ArgTypes of="bq-drawer" />
+  </div>
+</div>