feat(components): add an Overlay component

* add useScrollbarWidth hook
* add useScrollLock hook
* add a new component to lock scroll with an overlay (it can be useful
especially on small screens to prevent background contents to be
scrolled)

6 files changed, 151 insertions, 0 deletions

diff --git a/src/components/atoms/index.ts b/src/components/atoms/index.ts
index 9791e66..54d8d29 100644
--- a/src/components/atoms/index.ts
+++ b/src/components/atoms/index.ts
@@ -9,5 +9,6 @@ export * from './links';
 export * from './lists';
 export * from './loaders';
 export * from './notice';
+export * from './overlay';
 export * from './sidebar';
 export * from './visually-hidden';
diff --git a/src/components/atoms/overlay/index.ts b/src/components/atoms/overlay/index.ts
new file mode 100644
index 0000000..40adbf0
--- /dev/null
+++ b/src/components/atoms/overlay/index.ts
@@ -0,0 +1 @@
+export * from './overlay';
diff --git a/src/components/atoms/overlay/overlay.module.scss b/src/components/atoms/overlay/overlay.module.scss
new file mode 100644
index 0000000..edbc4ae
--- /dev/null
+++ b/src/components/atoms/overlay/overlay.module.scss
@@ -0,0 +1,18 @@
+.overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 100;
+  background: hsla(0, 0%, 0%, 0.6);
+  transition: all 0.3s linear 0s;
+
+  &--hidden {
+    opacity: 0;
+    overflow: hidden;
+    visibility: hidden;
+  }
+
+  &--visible {
+    opacity: 1;
+    visibility: visible;
+  }
+}
diff --git a/src/components/atoms/overlay/overlay.stories.tsx b/src/components/atoms/overlay/overlay.stories.tsx
new file mode 100644
index 0000000..f9c478c
--- /dev/null
+++ b/src/components/atoms/overlay/overlay.stories.tsx
@@ -0,0 +1,63 @@
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+import { useToggle } from '../../../utils/hooks';
+import { Button } from '../buttons';
+import { Overlay } from './overlay';
+
+/**
+ * Overlay - Storybook Meta
+ */
+export default {
+  title: 'Atoms/Overlay',
+  component: Overlay,
+  argTypes: {},
+} as ComponentMeta<typeof Overlay>;
+
+const Template: ComponentStory<typeof Overlay> = ({ isVisible, ...props }) => {
+  const [isActive, toggle] = useToggle(isVisible);
+
+  return (
+    <div>
+      <p>
+        Itaque reprehenderit sint rerum placeat et sapiente similique ut
+        distinctio. Libero illo reprehenderit qui quaerat dolorem. Officiis
+        asperiores sapiente eaque. Aut numquam porro quasi delectus excepturi
+        aut eaque et. Commodi et necessitatibus provident blanditiis rem qui
+        atque.
+      </p>
+      <p>
+        Aut architecto vitae dolor hic explicabo iure quia quae beatae.
+        Exercitationem nulla dignissimos doloribus sunt at nisi. A modi quasi
+        est sed quas repellendus vel sed dolores. Sed neque aperiam adipisci eos
+        autem. Libero omnis quis aut quas omnis magni harum et.
+      </p>
+      <Button onClick={toggle}>Open overlay</Button>
+      <Overlay {...props} isVisible={isActive} onClick={toggle} />
+    </div>
+  );
+};
+
+/**
+ * Overlay Stories - Hidden
+ */
+export const Hidden = Template.bind({});
+Hidden.args = {
+  children: (
+    <div style={{ background: '#FFF', margin: '1rem', padding: '1rem' }}>
+      Some modal contents.
+    </div>
+  ),
+  isVisible: false,
+};
+
+/**
+ * Overlay Stories - Visible
+ */
+export const Visible = Template.bind({});
+Visible.args = {
+  children: (
+    <div style={{ background: '#FFF', margin: '1rem', padding: '1rem' }}>
+      Some modal contents.
+    </div>
+  ),
+  isVisible: true,
+};
diff --git a/src/components/atoms/overlay/overlay.test.tsx b/src/components/atoms/overlay/overlay.test.tsx
new file mode 100644
index 0000000..fcc694f
--- /dev/null
+++ b/src/components/atoms/overlay/overlay.test.tsx
@@ -0,0 +1,21 @@
+import { describe, expect, it } from '@jest/globals';
+import { render, screen as screenTL } from '@testing-library/react';
+import { Overlay } from './overlay';
+
+describe('overlay', () => {
+  it('renders its children in front of an overlay', () => {
+    const body = 'perferendis voluptatibus ut';
+
+    render(<Overlay>{body}</Overlay>);
+
+    expect(screenTL.getByText(body)).toHaveClass('overlay--visible');
+  });
+
+  it('can be hidden', () => {
+    const body = 'vel aspernatur mollitia';
+
+    render(<Overlay isVisible={false}>{body}</Overlay>);
+
+    expect(screenTL.getByText(body)).toHaveClass('overlay--hidden');
+  });
+});
diff --git a/src/components/atoms/overlay/overlay.tsx b/src/components/atoms/overlay/overlay.tsx
new file mode 100644
index 0000000..7dd7446
--- /dev/null
+++ b/src/components/atoms/overlay/overlay.tsx
@@ -0,0 +1,47 @@
+import {
+  forwardRef,
+  type ForwardRefRenderFunction,
+  type HTMLAttributes,
+  type ReactNode,
+} from 'react';
+import { useScrollLock } from '../../../utils/hooks';
+import styles from './overlay.module.scss';
+
+export type OverlayProps = HTMLAttributes<HTMLDivElement> & {
+  /**
+   * The elements to display in front of the overlay.
+   */
+  children: ReactNode;
+  /**
+   * Should the overlay be visible?
+   *
+   * Use it if you want an animated overlay instead of mounting/demounting it.
+   *
+   * @default true
+   */
+  isVisible?: boolean;
+};
+
+const OverlayWithRef: ForwardRefRenderFunction<HTMLDivElement, OverlayProps> = (
+  { children, className = '', isVisible = true, ...props },
+  ref
+) => {
+  const overlayClass = [
+    styles.overlay,
+    styles[isVisible ? 'overlay--visible' : 'overlay--hidden'],
+    className,
+  ].join(' ');
+
+  useScrollLock(isVisible);
+
+  return (
+    <div {...props} className={overlayClass} ref={ref}>
+      {children}
+    </div>
+  );
+};
+
+/**
+ * Overlay component.
+ */
+export const Overlay = forwardRef(OverlayWithRef);