Feat: Introduce Drawer component #DS-1580

packages/web-react/scripts/entryPoints.js

@@ -21,6 +21,7 @@ const entryPoints = [
   { dirs: ['components', 'Container'] },
   { dirs: ['components', 'Dialog'] },
   { dirs: ['components', 'Divider'] },
+  { dirs: ['components', 'Drawer'] },
   { dirs: ['components', 'Dropdown'] },
   { dirs: ['components', 'Field'] },
   { dirs: ['components', 'FieldGroup'] },

packages/web-react/src/components/Drawer/Drawer.tsx

@@ -0,0 +1,41 @@
+'use client';
+
+import classNames from 'classnames';
+import React from 'react';
+import { useStyleProps, useLastActiveFocus } from '../../hooks';
+import { SpiritDrawerProps } from '../../types';
+import { Dialog } from '../Dialog';
+import { DRAWER_ALIGNMENT_DEFAULT } from './constants';
+import { DrawerProvider } from './DrawerContext';
+import { useDrawerStyleProps } from './useDrawerStyleProps';
+
+const Drawer = (props: SpiritDrawerProps) => {
+  const { children, alignmentX = DRAWER_ALIGNMENT_DEFAULT, isOpen, onClose, id, ...restProps } = props;
+  const { classProps } = useDrawerStyleProps({ drawerAlignmentX: alignmentX });
+  const { styleProps, props: otherProps } = useStyleProps(restProps);
+
+  const contextValue = {
+    id,
+    isOpen,
+    onClose,
+  };
+
+  useLastActiveFocus(isOpen);
+
+  return (
+    <DrawerProvider value={contextValue}>
+      <Dialog
+        {...otherProps}
+        {...styleProps}
+        id={id}
+        isOpen={isOpen}
+        onClose={onClose}
+        className={classNames(classProps.root, styleProps.className)}
+      >
+        {children}
+      </Dialog>
+    </DrawerProvider>
+  );
+};
+
+export default Drawer;

packages/web-react/src/components/Drawer/DrawerCloseButton.tsx

@@ -0,0 +1,38 @@
+'use client';
+
+import classNames from 'classnames';
+import React from 'react';
+import { useStyleProps } from '../../hooks';
+import { DrawerCloseButtonProps } from '../../types';
+import { Button } from '../Button';
+import { Icon } from '../Icon';
+import { VisuallyHidden } from '../VisuallyHidden';
+import { DRAWER_CLOSE_BUTTON_LABEL_DEFAULT } from './constants';
+import { useDrawerContext } from './DrawerContext';
+import { useDrawerStyleProps } from './useDrawerStyleProps';
+
+const DrawerCloseButton = (props: DrawerCloseButtonProps) => {
+  const { label = DRAWER_CLOSE_BUTTON_LABEL_DEFAULT, ...restProps } = props;
+  const { id, isOpen, onClose } = useDrawerContext();
+
+  const { classProps } = useDrawerStyleProps();
+  const { styleProps, props: otherProps } = useStyleProps(restProps);
+
+  return (
+    <Button
+      {...otherProps}
+      aria-expanded={isOpen}
+      aria-controls={id}
+      onClick={onClose}
+      color="tertiary"
+      UNSAFE_className={classNames(classProps.closeButton, styleProps.className)}
+      UNSAFE_style={styleProps.style}
+      isSymmetrical
+    >
+      <Icon name="close" />
+      <VisuallyHidden>{label}</VisuallyHidden>
+    </Button>
+  );
+};
+
+export default DrawerCloseButton;

packages/web-react/src/components/Drawer/DrawerContext.ts

@@ -0,0 +1,22 @@
+'use client';
+
+import { createContext, useContext } from 'react';
+import { DrawerPanelHandlingProps } from '../../types';
+
+export type DrawerContextProps = {
+  id: string;
+} & DrawerPanelHandlingProps;
+
+const defaultContext: DrawerContextProps = {
+  id: '',
+  isOpen: false,
+  onClose: () => null,
+};
+
+const DrawerContext = createContext<DrawerContextProps>(defaultContext);
+const DrawerProvider = DrawerContext.Provider;
+const DrawerConsumer = DrawerContext.Consumer;
+const useDrawerContext = (): DrawerContextProps => useContext(DrawerContext);
+
+export default DrawerContext;
+export { DrawerProvider, DrawerConsumer, useDrawerContext };

packages/web-react/src/components/Drawer/DrawerPanel.tsx

@@ -0,0 +1,34 @@
+'use client';
+
+import classNames from 'classnames';
+import React, { ElementType, ForwardedRef, forwardRef, HTMLAttributes } from 'react';
+import { useStyleProps } from '../../hooks';
+import { DrawerPanelElementType, DrawerPanelProps } from '../../types';
+import { useDrawerStyleProps } from './useDrawerStyleProps';
+
+/* We need an exception for components exported with forwardRef */
+/* eslint no-underscore-dangle: ['error', { allow: ['_DrawerPanel'] }] */
+const _DrawerPanel = <E extends ElementType = DrawerPanelElementType>(
+  props: DrawerPanelProps<E>,
+  ref: ForwardedRef<HTMLDivElement>,
+) => {
+  const { elementType: ElementTag = 'div', children, ...restProps } = props;
+
+  const { classProps } = useDrawerStyleProps(restProps);
+  const { styleProps, props: otherProps } = useStyleProps(restProps);
+
+  return (
+    <ElementTag
+      ref={ref}
+      {...(otherProps as HTMLAttributes<HTMLElement>)}
+      className={classNames(classProps.panel, styleProps.className)}
+      style={styleProps.style}
+    >
+      <div className={classProps.content}>{children}</div>
+    </ElementTag>
+  );
+};
+
+const DrawerPanel = forwardRef<HTMLDivElement, DrawerPanelProps<ElementType>>(_DrawerPanel);
+
+export default DrawerPanel;

packages/web-react/src/components/Drawer/README.md

@@ -0,0 +1,145 @@
+# Drawer
+
+The Drawer component is a container that slides in from side of the screen. It can be used to display additional content or actions that are not part of the main view.
+
+The Drawer is a composition of several subcomponents:
+
+- [Drawer](#drawer)
+  - [DrawerCloseButton](#drawerclosebutton)
+  - [DrawerPanel](#drawerpanel)
+
+## Accessibility Guidelines
+
+👉 The animation effect of this component is dependent on the
+`prefers-reduced-motion` media query.
+
+## Drawer
+
+```jsx
+import { Drawer } from '@lmc-eu/spirit-web-react';
+
+const [isOpen, setOpen] = useState(false);
+
+<Drawer id="drawer-dialog-example" isOpen={isOpen} onClose={() => setOpen(false)}>
+  {/* Drawer Panel goes here */}
+</Drawer>;
+```
+
+### Alignment
+
+The `Drawer` component allows aligning the content panel horizontally to the left or right side of the screen using `alignmentX` prop. By default, the drawer content panel is aligned to the right.
+
+```jsx
+<Drawer id="drawer-dialog-example" isOpen={isOpen} onClose={() => setOpen(false)} alignmentX="left">
+  {/* Drawer Panel goes here */}
+</Drawer>
+```
+
+### Close on Backdrop Click
+
+By default, the drawer will close when the backdrop is clicked. You can disable this behavior by setting the `closeOnBackdropClick` prop to `false`.
+
+```jsx
+<Drawer id="drawer-dialog-example" isOpen={isOpen} onClose={() => setOpen(false)} closeOnBackdropClick={false}>
+  {/* Drawer content goes here */}
+</Drawer>
+```
+
+### Close on Escape Key Down
+
+By default, the drawer will close when the escape key is pressed. You can disable this behavior by setting the `closeOnEscapeKeyDown` prop to `false`.
+
+```jsx
+<Drawer id="drawer-dialog-example" isOpen={isOpen} onClose={() => setOpen(false)} closeOnEscapeKeyDown={false}>
+  {/* Drawer content goes here */}
+</Drawer>
+```
+
+### API
+
+| Name                   | Type                                           | Default | Required | Description                                              |
+| ---------------------- | ---------------------------------------------- | ------- | -------- | -------------------------------------------------------- |
+| `alignmentX`           | `left` \| `right`                              | `right` | ✕        | Drawer horizontal alignment                              |
+| `children`             | `ReactNode`                                    | —       | ✕        | Children node                                            |
+| `closeOnBackdropClick` | `bool`                                         | `true`  | ✕        | Whether the drawer will close when backdrop is clicked   |
+| `closeOnEscapeKeyDown` | `bool`                                         | `true`  | ✕        | Whether the drawer will close when escape key is pressed |
+| `id`                   | `string`                                       | —       | ✓        | ID to be linked                                          |
+| `isOpen`               | `bool`                                         | `false` | ✓        | Open state                                               |
+| `onClose`              | `(event: ClickEvent or KeyboardEvent) => void` | —       | ✓        | Callback for drawer when closed                          |
+
+The component further inherits properties from the [`<dialog>`][mdn-dialog-element] element.
+
+On top of the API options, the components accept [additional attributes][readme-additional-attributes].
+If you need more control over the styling of a component, you can use [style props][readme-style-props]
+and [escape hatches][readme-escape-hatches].
+
+## DrawerCloseButton
+
+The `DrawerCloseButton` component is a button that closes the drawer when clicked.
+
+```jsx
+import { DrawerCloseButton } from '@lmc-eu/spirit-web-react';
+
+<DrawerCloseButton />;
+```
+
+### API
+
+| Name    | Type     | Default | Required | Description                      |
+| ------- | -------- | ------- | -------- | -------------------------------- |
+| `label` | `string` | `Close` | ✕        | Label of the drawer close button |
+
+The component further inherits properties from the [`<button>`][mdn-button-element] element.
+
+On top of the API options, the components accept [additional attributes][readme-additional-attributes].
+If you need more control over the styling of a component, you can use [style props][readme-style-props]
+and [escape hatches][readme-escape-hatches].
+
+## DrawerPanel
+
+The `DrawerPanel` component is a container for the content that will be displayed in the drawer.
+
+```jsx
+import { DrawerPanel } from '@lmc-eu/spirit-web-react';
+
+<DrawerPanel>{/* Drawer content goes here */}</DrawerPanel>;
+```
+
+### API
+
+| Name          | Type          | Default | Required | Description                          |
+| ------------- | ------------- | ------- | -------- | ------------------------------------ |
+| `children`    | `ReactNode`   | —       | ✕        | Children node                        |
+| `elementType` | `ElementType` | `div`   | ✕        | Type of element used as drawer panel |
+
+## Full Example
+
+```jsx
+import { Drawer, DrawerPanel, DrawerCloseButton } from '@lmc-eu/spirit-web-react';
+
+const [isOpen, setIsOpen] = useState(false);
+
+const handleOpen = () => setIsOpen(true);
+const handleClose = () => setIsOpen(false);
+
+<Button onClick={handleOpen} aria-controls="drawer-example">
+  Open Drawer
+</Button>
+
+<Drawer
+  id="drawer-example"
+  isOpen={isOpen}
+  onClose={handleClose}
+>
+  <DrawerPanel>
+    <DrawerCloseButton />
+    <div>Drawer content</div>
+  </DrawerPanel>
+</Drawer>
+```
+
+[mdn-button-element]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button
+[mdn-dialog-element]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog
+[readme-additional-attributes]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-react/README.md#additional-attributes
+[readme-escape-hatches]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-react/README.md#escape-hatches
+[readme-style-props]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-react/README.md#style-props

packages/web-react/src/components/Drawer/__tests__/Drawer.test.tsx

@@ -0,0 +1,68 @@
+import '@testing-library/jest-dom';
+import { fireEvent, render, screen } from '@testing-library/react';
+import React from 'react';
+import { classNamePrefixProviderTest, restPropsTest, stylePropsTest } from '@local/tests';
+import { SpiritDrawerProps } from '../../../types';
+import Drawer from '../Drawer';
+
+const mockedOnClose = jest.fn();
+
+describe('Drawer', () => {
+  const DrawerTest = (props: SpiritDrawerProps) => (
+    <Drawer {...props} id="drawer-example" isOpen={false} onClose={() => null}>
+      <div>Test</div>
+    </Drawer>
+  );
+
+  classNamePrefixProviderTest(DrawerTest, 'Drawer');
+
+  stylePropsTest(DrawerTest);
+
+  restPropsTest(DrawerTest, 'dialog');
+
+  it('should not close drawer', () => {
+    render(
+      <Drawer id="test" isOpen onClose={mockedOnClose} closeOnBackdropClick={false}>
+        <div>Test</div>
+      </Drawer>,
+    );
+
+    const dialog = screen.getByRole('dialog');
+    fireEvent.click(dialog);
+
+    expect(mockedOnClose).not.toHaveBeenCalled();
+  });
+
+  it('should close drawer', () => {
+    render(
+      <Drawer id="test" isOpen onClose={mockedOnClose} closeOnBackdropClick>
+        <div>Test</div>
+      </Drawer>,
+    );
+
+    const dialog = screen.getByRole('dialog');
+    fireEvent.click(dialog);
+
+    expect(mockedOnClose).toHaveBeenCalled();
+  });
+
+  it('should render drawer content', () => {
+    render(
+      <Drawer id="test" isOpen onClose={mockedOnClose}>
+        <div>Test</div>
+      </Drawer>,
+    );
+
+    expect(screen.getByRole('dialog')).toHaveTextContent('Test');
+  });
+
+  it('should render drawer with correct alignment class', () => {
+    render(
+      <Drawer id="test" isOpen onClose={mockedOnClose} alignmentX="left">
+        <div>Test</div>
+      </Drawer>,
+    );
+
+    expect(screen.getByRole('dialog')).toHaveClass('Drawer--left');
+  });
+});

packages/web-react/src/components/Drawer/__tests__/DrawerCloseButton.test.tsx

@@ -0,0 +1,25 @@
+import '@testing-library/jest-dom';
+import { render, screen } from '@testing-library/react';
+import React from 'react';
+import { classNamePrefixProviderTest, restPropsTest, stylePropsTest } from '@local/tests';
+import DrawerCloseButton from '../DrawerCloseButton';
+
+describe('DrawerCloseButton', () => {
+  classNamePrefixProviderTest(DrawerCloseButton, 'DrawerCloseButton');
+
+  stylePropsTest(DrawerCloseButton);
+
+  restPropsTest(DrawerCloseButton, 'button');
+
+  it('should render drawer close button', () => {
+    render(<DrawerCloseButton />);
+
+    expect(screen.getByRole('button')).toHaveClass('DrawerCloseButton');
+  });
+
+  it('should render with correct class', () => {
+    render(<DrawerCloseButton data-testid="test" />);
+
+    expect(screen.getByTestId('test')).toHaveClass('DrawerCloseButton');
+  });
+});