@stack-spot/portal-layout 1.0.2 → 1.1.0

package/src/LayoutOverlayManager.tsx

@@ -1,464 +1,464 @@
-/* eslint-disable react-hooks/rules-of-hooks */
-
-import { Button } from '@citric/core'
-import { focusAccessibleElement, focusFirstChild } from '@stack-spot/portal-components'
-import { ReactElement, useLayoutEffect, useState } from 'react'
-import { Dialog, DialogOptions } from './components/Dialog'
-import { CLOSE_OVERLAY_ID, OverlayContent, OverlayContentProps } from './components/OverlayContent'
-import { getDictionary } from './dictionary'
-import { LayoutElements, elementIds, getLayoutElements } from './elements'
-import { ElementNotFound, LayoutError } from './errors'
-import { CustomToasterOptions, DefaultToasterOptions, closeReactToaster, showToaster as showReactToaster } from './toaster'
-import { valueOfLayoutVar } from './utils'
-
-interface AlertOptions extends Omit<DialogOptions, 'cancel'> {
-  /**
-   * Whether or not to show an "ok" button. If false, the dialog can still be closed through the close button, by clicking outside it or by
-   * pressing ESC.
-   */
-  showButton?: boolean,
-}
-
-type BottomDialogOptions = Omit<DialogOptions, 'title'>
-type OverlaySize = 'small' | 'medium' | 'large'
-type ModalSize = 'fit-content' | OverlaySize
-type SetContentFn = ((content: ReactElement | undefined) => void) | undefined
-
-interface OverlayContentSetter {
-  modal?: SetContentFn,
-  rightPanel?: SetContentFn,
-  bottomDialog?: SetContentFn,
-}
-
-interface CustomModalOptions {
-  /**
-   * The size of the modal.
-   */
-  size?: ModalSize,
-  /**
-   * A function to call when the modal closes. 
-   */
-  onClose?: () => void,
-}
-
-interface CustomRightPanelOptions {
-  /**
-   * The size of the right panel.
-   */
-  size?: OverlaySize,
-  /**
-   * A function to call when the right panel closes. 
-   */
-  onClose?: () => void,
-}
-
-function multipleCallsWarning(type: 'modal' | 'rightPanel', timeMS: number) {
-  return `
-    Attempted to show a modal or rightPanel while a ${type} was still being closed. Closing a ${type} takes only ${timeMS}ms, so this action
-    is unlikely to have been triggered by the user and may point to errors in your code. Please check.\nTip: showModal and showRightPanel
-    are sideEffects and should never be called during the render of a component. Try to use "useEffect" or link it to an event, like
-    "onClick".
-  `.replace(/\s*\n\s+/g, ' ')
-}
-
-class LayoutOverlayManager {
-  static readonly instance?: LayoutOverlayManager
-  private setContent: OverlayContentSetter = {}
-  private elements?: LayoutElements
-  private onModalClose?: () => void
-  /**
-   * Last element with focus before an overlay is shown.
-   */
-  private lastActiveElement: Element | null = null
-
-  private setupElements() {
-    this.elements = getLayoutElements()
-    this.elements.backdrop?.addEventListener('mousedown', (event) => {
-      if (this.isModalOpen()) !this.elements?.modal?.contains?.(event.target as Node) && this.closeModal()
-      else if (this.isRightPanelOpen()) !this.elements?.rightPanel?.contains?.(event.target as Node) && this.closeRightPanel()
-      else this.setMainContentInteractivity(true)
-    })
-    this.elements.backdrop?.addEventListener('keydown', (event) => {
-      if (event.key !== 'Escape') return
-      if (this.isModalOpen()) this.closeModal()
-      if (this.isRightPanelOpen()) this.closeRightPanel()
-      else this.setMainContentInteractivity(true)
-      event.preventDefault()
-    })
-    this.setInteractivity(this.elements?.modal, false)
-    this.setInteractivity(this.elements?.rightPanel, false)
-    this.setInteractivity(this.elements?.bottomDialog, false)
-  }
-  
-  /**
-   * Setup the overlay layout elements.
-   * @returns the content for the modal, rightPanel and bottomDialog.
-   */
-  // @ts-ignore: this should actually be like Kotlin's "internal", i.e. private to any user of the lib, but public to the lib itself.
-  private useOverlays() {
-    useLayoutEffect(() => {
-      if (!this.elements) this.setupElements()
-    }, [])
-    const [modal, setModal] = useState<ReactElement | undefined>()
-    const [rightPanel, setRightPanel] = useState<ReactElement | undefined>()
-    const [bottomDialog, setBottomDialog] = useState<ReactElement | undefined>()
-    this.setContent.modal = setModal
-    this.setContent.rightPanel = setRightPanel
-    this.setContent.bottomDialog = setBottomDialog
-    return { modal, rightPanel, bottomDialog }
-  }
-
-  /**
-   * Enables or disables the interactivity of an element.
-   * @param element the element to have its interactivity changed.
-   * @param interactive false to disable interactivity, true to enable.
-   */
-  private setInteractivity(element: HTMLElement | null | undefined, interactive: boolean) {
-    if (interactive) {
-      element?.removeAttribute('inert')
-      element?.removeAttribute('aria-hidden')
-    } else {
-      element?.setAttribute('aria-hidden', '')
-      element?.setAttribute('inert', '')
-    }
-  }
-
-  private setMainContentInteractivity(interactive: boolean) {
-    this.setInteractivity(this.elements?.page, interactive)
-    this.setInteractivity(this.elements?.header, interactive)
-    this.setInteractivity(this.elements?.menu, interactive)
-    this.elements?.backdrop?.setAttribute('class', interactive ? '' : 'visible')
-  }
-
-  private showOverlay(element: HTMLElement | null | undefined, extraClasses: string[] = [], blockMainContent = true) {
-    this.lastActiveElement = document.activeElement
-    element?.classList.add('visible', ...extraClasses)
-    this.setInteractivity(element, true)
-    if (blockMainContent) this.setMainContentInteractivity(false)
-    setTimeout(() => focusFirstChild(
-      element,
-      { priority: [['input', 'textarea', 'select', 'other', 'button']], ignore: `#${CLOSE_OVERLAY_ID}` },
-    ), 50)
-  }
-
-  private hideOverlay(element: HTMLElement | null | undefined) {
-    element?.setAttribute('class', '')
-    this.setInteractivity(element, false)
-    this.setMainContentInteractivity(true)
-  }
-
-  /**
-   * @returns true if the modal is currently opened. False otherwise.
-   */
-  isModalOpen() {
-    return this.elements?.modal?.classList.contains('visible') ?? false
-  }
-
-  /**
-   * @returns true if the right panel is currently opened. False otherwise.
-   */
-  isRightPanelOpen() {
-    return this.elements?.rightPanel?.classList.contains('visible') ?? false
-  }
-
-  /**
-   * @returns true if the bottom dialog is currently opened. False otherwise.
-   */
-  isBottomDialogOpen() {
-    return this.elements?.bottomDialog?.classList.contains('visible') ?? false
-  }
-
-  /**
-   * Opens a modal with custom content.
-   * 
-   * Attention: the modal state must be declared within the modal. If the state is declared outside the modal, its content won't be updated
-   * accordingly. To force an update of an outside state, you need to call `showCustomModal` again with the new state value.
-   * 
-   * @param content a react element with the modal content.
-   * @param options the modal options {@link CustomModalOptions}.
-   */
-  showCustomModal(content: React.ReactElement, { size = 'medium', onClose }: CustomModalOptions = {}) {
-    if (!this.elements?.modal) throw new ElementNotFound('modal', elementIds.modal)
-    if (!this.setContent.modal) throw new LayoutError('unable to show modal, because it has not been setup yet.')
-    this.onModalClose = onClose
-    this.setContent.modal(content)
-    this.showOverlay(this.elements.modal, [size])
-  }
-
-  /**
-   * Opens a modal.
-   * 
-   * Attention: the modal state must be declared within the modal. If the state is declared outside the modal, its content won't be updated
-   * accordingly. To force an update of an outside state, you need to call `showModal` again with the new state value.
-   * 
-   * @param options the modal options: {@link OverlayContentProps} & { size: {@link ModalSize} }.
-   */
-  showModal({ size, ...props }: OverlayContentProps & { size?: ModalSize }) {
-    this.showCustomModal(<OverlayContent {...props} onClose={() => this.closeModal()} type="modal" />, { size, onClose: props.onClose })
-  }
-
-  private showDialog(options: DialogOptions): Promise<boolean> {
-    let dialogResult = false
-    return new Promise((resolve, reject) => {
-      try {
-        this.showCustomModal(
-          <Dialog
-            {...options}
-            onCancel={() => this.closeModal()}
-            onConfirm={() => {
-              dialogResult = true
-              this.closeModal()
-            }}
-          />,
-          { size: 'small', onClose: () => resolve(dialogResult) },
-        )
-      } catch (error) {
-        reject(error)
-      }
-    })
-  }
-
-  /**
-   * Shows a confirmation dialog and returns a promise that resolves as soon as the dialog is closed. The result of the promise is true if
-   * the user confirms and false otherwise.
-   * 
-   * If you need the user to type something to confirm the action, use the property `validate` in the options parameter.
-   * @param options the dialog options: {@link DialogOptions}.
-   * @returns a promise that resolves with the user's answer.
-   */
-  confirm({ confirm, cancel, ...options }: DialogOptions): Promise<boolean> {
-    const t = getDictionary()
-    return this.showDialog({ ...options, confirm: confirm || t.confirm, cancel: cancel || t.cancel })
-  }
-
-  /**
-   * Shows an alert dialog and returns a promise that resolves as soon as the dialog is closed.
-   * 
-   * @param options the dialog options: {@link AlertOptions}.
-   * @returns a promise that resolves to undefined as soon as the dialog is closed.
-   */
-  async alert({ confirm, showButton = true, ...options }: AlertOptions): Promise<void> {
-    const t = getDictionary()
-    await this.showDialog({ ...options, confirm: showButton ? (confirm || t.confirm) : undefined })
-  }
-
-  /**
-   * Shows a message at the bottom of the window and asks the user to confirm or decline it. The return value is a promise that resolves as
-   * soon as the user presses one of the buttons. The result of the promise is true if the user confirms and false otherwise.
-   * 
-   * Differently than `confirm` and `alert`, this message can only be closed if the user clicks one of the buttons or `closeBottomDialog`
-   * is called.
-   * 
-   * @param options the dialog options: {@link BottomDialogOptions}.
-   * @returns a promise that resolves with the user's answer.
-   */
-  showBottomDialog({ children, cancel, confirm }: BottomDialogOptions): Promise<boolean> {
-    if (!this.elements?.bottomDialog) throw new ElementNotFound('bottom dialog', elementIds.bottomDialog)
-    if (!this.setContent.bottomDialog) throw new LayoutError('unable to show bottom dialog, because it has not been setup yet.')
-    return new Promise((resolve) => {
-      this.setContent.bottomDialog?.(
-        <>
-          {children}
-          <div className="btn-group">
-            {cancel && <Button onClick={() => resolve(false)} colorScheme="light" appearance="outlined">{cancel}</Button>}
-            {confirm && <Button onClick={() => resolve(true)} colorScheme="light">{confirm}</Button>}
-          </div>
-        </>,
-      )
-      this.showOverlay(this.elements?.bottomDialog, undefined, false)
-    })
-  }
-
-  /**
-   * Opens a right panel with custom content.
-   * 
-   * Attention: the right panel state must be declared within the right panel. If the state is declared outside the right panel, its content
-   * won't be updated accordingly. To force an update of an outside state, you need to call `showCustomRightPanel` again with the new state
-   * value.
-   * 
-   * @param content a react element with the modal content.
-   * @param options the modal options {@link CustomModalOptions}.
-   */
-  showCustomRightPanel(content: ReactElement, { size = 'medium', onClose }: CustomRightPanelOptions = {}) {
-    if (!this.elements?.rightPanel) throw new ElementNotFound('right panel overlay', elementIds.rightPanel)
-    if (!this.setContent.rightPanel) throw new LayoutError('unable to show right panel overlay, because it has not been setup yet.')
-    this.onModalClose = onClose
-    this.setContent.rightPanel(content)
-    this.elements?.rightPanel.classList.add(size)
-    setTimeout(() => {
-      this.showOverlay(this.elements?.rightPanel)
-    })
-  }
-
-  /**
-   * Opens a right panel.
-   * 
-   * Attention: the right panel state must be declared within the right panel. If the state is declared outside the right panel, its content
-   * won't be updated accordingly. To force an update of an outside state, you need to call `showRightPanel` again with the new state value.
-   * 
-   * @param options the modal options: {@link OverlayContentProps} & { size: {@link ModalSize} }.
-   */
-  showRightPanel({ size, ...props }: OverlayContentProps & { size?: OverlaySize }) {
-    this.showCustomRightPanel(
-      <OverlayContent {...props} onClose={() => this.closeRightPanel()} type="panel" />,
-      { size, onClose: props.onClose },
-    )
-  }
-
-  /*
-   * Focus the element that had focus before the last overlay was opened. If the element is not visible anymore, another one that makes
-   * sense (accessibility-wise) is focused.
-   */
-  private focusLastActiveElement() {
-    focusAccessibleElement(this.lastActiveElement)
-    this.lastActiveElement = null
-  }
-
-  /**
-   * Closes the modal if it's open.
-   * @param runCloseListener whether or not to run the function `onClose` passed to `showModal` or `showCustomModal`. Defaults to true.
-   */
-  closeModal(runCloseListener = true) {
-    this.elements?.modal?.classList.remove('visible')
-    this.elements?.backdrop?.setAttribute('class', '')
-    if (runCloseListener && this.onModalClose) {
-      const onClose = this.onModalClose
-      // setting it to undefined before running it prevents nested calls to closeModal from generating infinite loops.
-      this.onModalClose = undefined
-      onClose()
-    }
-    const animationMS = parseFloat(valueOfLayoutVar('--modal-animation-duration')) * 1000
-    setTimeout(
-      () => {
-        if (this.elements?.backdrop?.classList.contains('visible')) {
-          // eslint-disable-next-line no-console
-          console.warn(multipleCallsWarning('modal', animationMS))
-          this.elements?.modal?.classList.remove('visible')
-        }
-        if (this.setContent.modal) this.setContent.modal(undefined)
-        this.hideOverlay(this.elements?.modal)
-        this.focusLastActiveElement()
-      },
-      animationMS,
-    )
-  }
-
-  /**
-   * Closes the right panel if it's open.
-   * @param runCloseListener whether or not to run the function `onClose` passed to `showRightPanel` or `showCustomRightPanel`. Defaults to
-   * true.
-   */
-  closeRightPanel(runCloseListener = true) {
-    this.elements?.rightPanel?.classList.remove('visible')
-    this.elements?.backdrop?.setAttribute('class', '')
-    if (runCloseListener && this.onModalClose) {
-      const onClose = this.onModalClose
-      // setting it to undefined before running it prevents nested calls to closeRightPanel from generating infinite loops.
-      this.onModalClose = undefined
-      onClose()
-    }
-    const animationMS = parseFloat(valueOfLayoutVar('--right-panel-animation-duration')) * 1000
-    setTimeout(
-      () => {
-        if (this.elements?.backdrop?.classList.contains('visible')) {
-          // eslint-disable-next-line no-console
-          console.warn(multipleCallsWarning('rightPanel', animationMS))
-          this.elements?.rightPanel?.classList.remove('visible')
-        }
-        if (this.setContent.rightPanel) this.setContent.rightPanel(undefined)
-        this.hideOverlay(this.elements?.rightPanel)
-        this.focusLastActiveElement()
-      },
-      animationMS,
-    )
-  }
-
-  /**
-   * Closes the bottom dialog if it's open.
-   */
-  closeBottomDialog() {
-    this.hideOverlay(this.elements?.bottomDialog)
-  }
-
-  /**
-   * Verifies if the HTML element passed as parameter is inside the modal.
-   * @param element the HTML element to check.
-   * @returns true if `element` is inside the modal; false otherwise.
-   */
-  isInsideModal(element: HTMLElement) {
-    return !!this.elements?.modal?.contains(element)
-  }
-
-  /**
-   * Verifies if the HTML element passed as parameter is inside the right panel.
-   * @param element the HTML element to check.
-   * @returns true if `element` is inside the right panel; false otherwise.
-   */
-  isInsideRightPanel(element: HTMLElement) {
-    return !!this.elements?.rightPanel?.contains(element)
-  }
-
-  /**
-   * Shows a new toaster on the top right corner of the layout.
-   * @example
-   * ```
-   * overlay.showToaster({ title: 'Welcome', message: 'Hello World' })
-   * overlay.showToaster({
-   *   title: 'Welcome',
-   *   message: 'Hello World',
-   *   actions: [
-   *     { label: 'Got it!' },
-   *     {
-   *       label: 'Tell me more',
-   *       closeOnClick: false,
-   *       onClick: (event) => {
-   *         // do something...
-   *       },
-   *     },
-   *   ]
-   * })
-   * ```
-   * @param options the options for the toaster: {@link DefaultToasterOptions}.
-   * @returns the toaster's id.
-   */
-  showToaster(defaultToasterConfig: DefaultToasterOptions): number | string
-  /**
-   * Shows a fully customized toaster on the top right corner of the layout.
-   * @example
-   * ```
-   * overlay.showToaster({
-   *   custom: true,
-   *   message: <MyCustomToasterContent />,
-   *   closeButton: <MyCustomCloseButton />,
-   * })
-   * ```
-   * @param options the options for the toaster: {@link CustomToasterOptions}.
-   * @returns the toaster's id.
-   */
-  showToaster(customToasterConfig: CustomToasterOptions): number | string
-  /**
-   * Shows the message passed as parameter in a new toaster on the top right corner of the layout.
-   * @example
-   * ```
-   * overlay.showToaster('Hello World!')
-   * overlay.showToaster(<p>Hello World</p>)
-   * ```
-   * @param message the message to show, can be either a string or React Element.
-   * @returns the toaster's id.
-   */
-  showToaster(message: React.ReactNode): number | string
-  showToaster(options: any): number | string {
-    return showReactToaster(options)
-  }
-
-  /**
-   * Closes the toaster with the specified id.
-   * @param id the id of the toaster to close.
-   */
-  closeToaster = closeReactToaster
-}
-
-/**
- * Manages overlay components of the layout like: modal, rightPanel, bottomDialog and toaster.
- */
-export const overlay = new LayoutOverlayManager()
+/* eslint-disable react-hooks/rules-of-hooks */
+
+import { Button } from '@citric/core'
+import { focusAccessibleElement, focusFirstChild } from '@stack-spot/portal-components'
+import { ReactElement, useLayoutEffect, useState } from 'react'
+import { Dialog, DialogOptions } from './components/Dialog'
+import { CLOSE_OVERLAY_ID, OverlayContent, OverlayContentProps } from './components/OverlayContent'
+import { getDictionary } from './dictionary'
+import { LayoutElements, elementIds, getLayoutElements } from './elements'
+import { ElementNotFound, LayoutError } from './errors'
+import { CustomToasterOptions, DefaultToasterOptions, closeReactToaster, showToaster as showReactToaster } from './toaster'
+import { valueOfLayoutVar } from './utils'
+
+interface AlertOptions extends Omit<DialogOptions, 'cancel'> {
+  /**
+   * Whether or not to show an "ok" button. If false, the dialog can still be closed through the close button, by clicking outside it or by
+   * pressing ESC.
+   */
+  showButton?: boolean,
+}
+
+type BottomDialogOptions = Omit<DialogOptions, 'title'>
+type OverlaySize = 'small' | 'medium' | 'large'
+type ModalSize = 'fit-content' | OverlaySize
+type SetContentFn = ((content: ReactElement | undefined) => void) | undefined
+
+interface OverlayContentSetter {
+  modal?: SetContentFn,
+  rightPanel?: SetContentFn,
+  bottomDialog?: SetContentFn,
+}
+
+interface CustomModalOptions {
+  /**
+   * The size of the modal.
+   */
+  size?: ModalSize,
+  /**
+   * A function to call when the modal closes. 
+   */
+  onClose?: () => void,
+}
+
+interface CustomRightPanelOptions {
+  /**
+   * The size of the right panel.
+   */
+  size?: OverlaySize,
+  /**
+   * A function to call when the right panel closes. 
+   */
+  onClose?: () => void,
+}
+
+function multipleCallsWarning(type: 'modal' | 'rightPanel', timeMS: number) {
+  return `
+    Attempted to show a modal or rightPanel while a ${type} was still being closed. Closing a ${type} takes only ${timeMS}ms, so this action
+    is unlikely to have been triggered by the user and may point to errors in your code. Please check.\nTip: showModal and showRightPanel
+    are sideEffects and should never be called during the render of a component. Try to use "useEffect" or link it to an event, like
+    "onClick".
+  `.replace(/\s*\n\s+/g, ' ')
+}
+
+class LayoutOverlayManager {
+  static readonly instance?: LayoutOverlayManager
+  private setContent: OverlayContentSetter = {}
+  private elements?: LayoutElements
+  private onModalClose?: () => void
+  /**
+   * Last element with focus before an overlay is shown.
+   */
+  private lastActiveElement: Element | null = null
+
+  private setupElements() {
+    this.elements = getLayoutElements()
+    this.elements.backdrop?.addEventListener('mousedown', (event) => {
+      if (this.isModalOpen()) !this.elements?.modal?.contains?.(event.target as Node) && this.closeModal()
+      else if (this.isRightPanelOpen()) !this.elements?.rightPanel?.contains?.(event.target as Node) && this.closeRightPanel()
+      else this.setMainContentInteractivity(true)
+    })
+    this.elements.backdrop?.addEventListener('keydown', (event) => {
+      if (event.key !== 'Escape') return
+      if (this.isModalOpen()) this.closeModal()
+      if (this.isRightPanelOpen()) this.closeRightPanel()
+      else this.setMainContentInteractivity(true)
+      event.preventDefault()
+    })
+    this.setInteractivity(this.elements?.modal, false)
+    this.setInteractivity(this.elements?.rightPanel, false)
+    this.setInteractivity(this.elements?.bottomDialog, false)
+  }
+  
+  /**
+   * Setup the overlay layout elements.
+   * @returns the content for the modal, rightPanel and bottomDialog.
+   */
+  // @ts-ignore: this should actually be like Kotlin's "internal", i.e. private to any user of the lib, but public to the lib itself.
+  private useOverlays() {
+    useLayoutEffect(() => {
+      if (!this.elements) this.setupElements()
+    }, [])
+    const [modal, setModal] = useState<ReactElement | undefined>()
+    const [rightPanel, setRightPanel] = useState<ReactElement | undefined>()
+    const [bottomDialog, setBottomDialog] = useState<ReactElement | undefined>()
+    this.setContent.modal = setModal
+    this.setContent.rightPanel = setRightPanel
+    this.setContent.bottomDialog = setBottomDialog
+    return { modal, rightPanel, bottomDialog }
+  }
+
+  /**
+   * Enables or disables the interactivity of an element.
+   * @param element the element to have its interactivity changed.
+   * @param interactive false to disable interactivity, true to enable.
+   */
+  private setInteractivity(element: HTMLElement | null | undefined, interactive: boolean) {
+    if (interactive) {
+      element?.removeAttribute('inert')
+      element?.removeAttribute('aria-hidden')
+    } else {
+      element?.setAttribute('aria-hidden', '')
+      element?.setAttribute('inert', '')
+    }
+  }
+
+  private setMainContentInteractivity(interactive: boolean) {
+    this.setInteractivity(this.elements?.page, interactive)
+    this.setInteractivity(this.elements?.header, interactive)
+    this.setInteractivity(this.elements?.menu, interactive)
+    this.elements?.backdrop?.setAttribute('class', interactive ? '' : 'visible')
+  }
+
+  private showOverlay(element: HTMLElement | null | undefined, extraClasses: string[] = [], blockMainContent = true) {
+    this.lastActiveElement = document.activeElement
+    element?.classList.add('visible', ...extraClasses)
+    this.setInteractivity(element, true)
+    if (blockMainContent) this.setMainContentInteractivity(false)
+    setTimeout(() => focusFirstChild(
+      element,
+      { priority: [['input', 'textarea', 'select', 'other', 'button']], ignore: `#${CLOSE_OVERLAY_ID}` },
+    ), 50)
+  }
+
+  private hideOverlay(element: HTMLElement | null | undefined) {
+    element?.setAttribute('class', '')
+    this.setInteractivity(element, false)
+    this.setMainContentInteractivity(true)
+  }
+
+  /**
+   * @returns true if the modal is currently opened. False otherwise.
+   */
+  isModalOpen() {
+    return this.elements?.modal?.classList.contains('visible') ?? false
+  }
+
+  /**
+   * @returns true if the right panel is currently opened. False otherwise.
+   */
+  isRightPanelOpen() {
+    return this.elements?.rightPanel?.classList.contains('visible') ?? false
+  }
+
+  /**
+   * @returns true if the bottom dialog is currently opened. False otherwise.
+   */
+  isBottomDialogOpen() {
+    return this.elements?.bottomDialog?.classList.contains('visible') ?? false
+  }
+
+  /**
+   * Opens a modal with custom content.
+   * 
+   * Attention: the modal state must be declared within the modal. If the state is declared outside the modal, its content won't be updated
+   * accordingly. To force an update of an outside state, you need to call `showCustomModal` again with the new state value.
+   * 
+   * @param content a react element with the modal content.
+   * @param options the modal options {@link CustomModalOptions}.
+   */
+  showCustomModal(content: React.ReactElement, { size = 'medium', onClose }: CustomModalOptions = {}) {
+    if (!this.elements?.modal) throw new ElementNotFound('modal', elementIds.modal)
+    if (!this.setContent.modal) throw new LayoutError('unable to show modal, because it has not been setup yet.')
+    this.onModalClose = onClose
+    this.setContent.modal(content)
+    this.showOverlay(this.elements.modal, [size])
+  }
+
+  /**
+   * Opens a modal.
+   * 
+   * Attention: the modal state must be declared within the modal. If the state is declared outside the modal, its content won't be updated
+   * accordingly. To force an update of an outside state, you need to call `showModal` again with the new state value.
+   * 
+   * @param options the modal options: {@link OverlayContentProps} & { size: {@link ModalSize} }.
+   */
+  showModal({ size, ...props }: OverlayContentProps & { size?: ModalSize }) {
+    this.showCustomModal(<OverlayContent {...props} onClose={() => this.closeModal()} type="modal" />, { size, onClose: props.onClose })
+  }
+
+  private showDialog(options: DialogOptions): Promise<boolean> {
+    let dialogResult = false
+    return new Promise((resolve, reject) => {
+      try {
+        this.showCustomModal(
+          <Dialog
+            {...options}
+            onCancel={() => this.closeModal()}
+            onConfirm={() => {
+              dialogResult = true
+              this.closeModal()
+            }}
+          />,
+          { size: 'small', onClose: () => resolve(dialogResult) },
+        )
+      } catch (error) {
+        reject(error)
+      }
+    })
+  }
+
+  /**
+   * Shows a confirmation dialog and returns a promise that resolves as soon as the dialog is closed. The result of the promise is true if
+   * the user confirms and false otherwise.
+   * 
+   * If you need the user to type something to confirm the action, use the property `validate` in the options parameter.
+   * @param options the dialog options: {@link DialogOptions}.
+   * @returns a promise that resolves with the user's answer.
+   */
+  confirm({ confirm, cancel, ...options }: DialogOptions): Promise<boolean> {
+    const t = getDictionary()
+    return this.showDialog({ ...options, confirm: confirm || t.confirm, cancel: cancel || t.cancel })
+  }
+
+  /**
+   * Shows an alert dialog and returns a promise that resolves as soon as the dialog is closed.
+   * 
+   * @param options the dialog options: {@link AlertOptions}.
+   * @returns a promise that resolves to undefined as soon as the dialog is closed.
+   */
+  async alert({ confirm, showButton = true, ...options }: AlertOptions): Promise<void> {
+    const t = getDictionary()
+    await this.showDialog({ ...options, confirm: showButton ? (confirm || t.confirm) : undefined })
+  }
+
+  /**
+   * Shows a message at the bottom of the window and asks the user to confirm or decline it. The return value is a promise that resolves as
+   * soon as the user presses one of the buttons. The result of the promise is true if the user confirms and false otherwise.
+   * 
+   * Differently than `confirm` and `alert`, this message can only be closed if the user clicks one of the buttons or `closeBottomDialog`
+   * is called.
+   * 
+   * @param options the dialog options: {@link BottomDialogOptions}.
+   * @returns a promise that resolves with the user's answer.
+   */
+  showBottomDialog({ children, cancel, confirm }: BottomDialogOptions): Promise<boolean> {
+    if (!this.elements?.bottomDialog) throw new ElementNotFound('bottom dialog', elementIds.bottomDialog)
+    if (!this.setContent.bottomDialog) throw new LayoutError('unable to show bottom dialog, because it has not been setup yet.')
+    return new Promise((resolve) => {
+      this.setContent.bottomDialog?.(
+        <>
+          {children}
+          <div className="btn-group">
+            {cancel && <Button onClick={() => resolve(false)} colorScheme="light" appearance="outlined">{cancel}</Button>}
+            {confirm && <Button onClick={() => resolve(true)} colorScheme="light">{confirm}</Button>}
+          </div>
+        </>,
+      )
+      this.showOverlay(this.elements?.bottomDialog, undefined, false)
+    })
+  }
+
+  /**
+   * Opens a right panel with custom content.
+   * 
+   * Attention: the right panel state must be declared within the right panel. If the state is declared outside the right panel, its content
+   * won't be updated accordingly. To force an update of an outside state, you need to call `showCustomRightPanel` again with the new state
+   * value.
+   * 
+   * @param content a react element with the modal content.
+   * @param options the modal options {@link CustomModalOptions}.
+   */
+  showCustomRightPanel(content: ReactElement, { size = 'medium', onClose }: CustomRightPanelOptions = {}) {
+    if (!this.elements?.rightPanel) throw new ElementNotFound('right panel overlay', elementIds.rightPanel)
+    if (!this.setContent.rightPanel) throw new LayoutError('unable to show right panel overlay, because it has not been setup yet.')
+    this.onModalClose = onClose
+    this.setContent.rightPanel(content)
+    this.elements?.rightPanel.classList.add(size)
+    setTimeout(() => {
+      this.showOverlay(this.elements?.rightPanel)
+    })
+  }
+
+  /**
+   * Opens a right panel.
+   * 
+   * Attention: the right panel state must be declared within the right panel. If the state is declared outside the right panel, its content
+   * won't be updated accordingly. To force an update of an outside state, you need to call `showRightPanel` again with the new state value.
+   * 
+   * @param options the modal options: {@link OverlayContentProps} & { size: {@link ModalSize} }.
+   */
+  showRightPanel({ size, ...props }: OverlayContentProps & { size?: OverlaySize }) {
+    this.showCustomRightPanel(
+      <OverlayContent {...props} onClose={() => this.closeRightPanel()} type="panel" />,
+      { size, onClose: props.onClose },
+    )
+  }
+
+  /*
+   * Focus the element that had focus before the last overlay was opened. If the element is not visible anymore, another one that makes
+   * sense (accessibility-wise) is focused.
+   */
+  private focusLastActiveElement() {
+    focusAccessibleElement(this.lastActiveElement)
+    this.lastActiveElement = null
+  }
+
+  /**
+   * Closes the modal if it's open.
+   * @param runCloseListener whether or not to run the function `onClose` passed to `showModal` or `showCustomModal`. Defaults to true.
+   */
+  closeModal(runCloseListener = true) {
+    this.elements?.modal?.classList.remove('visible')
+    this.elements?.backdrop?.setAttribute('class', '')
+    if (runCloseListener && this.onModalClose) {
+      const onClose = this.onModalClose
+      // setting it to undefined before running it prevents nested calls to closeModal from generating infinite loops.
+      this.onModalClose = undefined
+      onClose()
+    }
+    const animationMS = parseFloat(valueOfLayoutVar('--modal-animation-duration')) * 1000
+    setTimeout(
+      () => {
+        if (this.elements?.backdrop?.classList.contains('visible')) {
+          // eslint-disable-next-line no-console
+          console.warn(multipleCallsWarning('modal', animationMS))
+          this.elements?.modal?.classList.remove('visible')
+        }
+        if (this.setContent.modal) this.setContent.modal(undefined)
+        this.hideOverlay(this.elements?.modal)
+        this.focusLastActiveElement()
+      },
+      animationMS,
+    )
+  }
+
+  /**
+   * Closes the right panel if it's open.
+   * @param runCloseListener whether or not to run the function `onClose` passed to `showRightPanel` or `showCustomRightPanel`. Defaults to
+   * true.
+   */
+  closeRightPanel(runCloseListener = true) {
+    this.elements?.rightPanel?.classList.remove('visible')
+    this.elements?.backdrop?.setAttribute('class', '')
+    if (runCloseListener && this.onModalClose) {
+      const onClose = this.onModalClose
+      // setting it to undefined before running it prevents nested calls to closeRightPanel from generating infinite loops.
+      this.onModalClose = undefined
+      onClose()
+    }
+    const animationMS = parseFloat(valueOfLayoutVar('--right-panel-animation-duration')) * 1000
+    setTimeout(
+      () => {
+        if (this.elements?.backdrop?.classList.contains('visible')) {
+          // eslint-disable-next-line no-console
+          console.warn(multipleCallsWarning('rightPanel', animationMS))
+          this.elements?.rightPanel?.classList.remove('visible')
+        }
+        if (this.setContent.rightPanel) this.setContent.rightPanel(undefined)
+        this.hideOverlay(this.elements?.rightPanel)
+        this.focusLastActiveElement()
+      },
+      animationMS,
+    )
+  }
+
+  /**
+   * Closes the bottom dialog if it's open.
+   */
+  closeBottomDialog() {
+    this.hideOverlay(this.elements?.bottomDialog)
+  }
+
+  /**
+   * Verifies if the HTML element passed as parameter is inside the modal.
+   * @param element the HTML element to check.
+   * @returns true if `element` is inside the modal; false otherwise.
+   */
+  isInsideModal(element: HTMLElement) {
+    return !!this.elements?.modal?.contains(element)
+  }
+
+  /**
+   * Verifies if the HTML element passed as parameter is inside the right panel.
+   * @param element the HTML element to check.
+   * @returns true if `element` is inside the right panel; false otherwise.
+   */
+  isInsideRightPanel(element: HTMLElement) {
+    return !!this.elements?.rightPanel?.contains(element)
+  }
+
+  /**
+   * Shows a new toaster on the top right corner of the layout.
+   * @example
+   * ```
+   * overlay.showToaster({ title: 'Welcome', message: 'Hello World' })
+   * overlay.showToaster({
+   *   title: 'Welcome',
+   *   message: 'Hello World',
+   *   actions: [
+   *     { label: 'Got it!' },
+   *     {
+   *       label: 'Tell me more',
+   *       closeOnClick: false,
+   *       onClick: (event) => {
+   *         // do something...
+   *       },
+   *     },
+   *   ]
+   * })
+   * ```
+   * @param options the options for the toaster: {@link DefaultToasterOptions}.
+   * @returns the toaster's id.
+   */
+  showToaster(defaultToasterConfig: DefaultToasterOptions): number | string
+  /**
+   * Shows a fully customized toaster on the top right corner of the layout.
+   * @example
+   * ```
+   * overlay.showToaster({
+   *   custom: true,
+   *   message: <MyCustomToasterContent />,
+   *   closeButton: <MyCustomCloseButton />,
+   * })
+   * ```
+   * @param options the options for the toaster: {@link CustomToasterOptions}.
+   * @returns the toaster's id.
+   */
+  showToaster(customToasterConfig: CustomToasterOptions): number | string
+  /**
+   * Shows the message passed as parameter in a new toaster on the top right corner of the layout.
+   * @example
+   * ```
+   * overlay.showToaster('Hello World!')
+   * overlay.showToaster(<p>Hello World</p>)
+   * ```
+   * @param message the message to show, can be either a string or React Element.
+   * @returns the toaster's id.
+   */
+  showToaster(message: React.ReactNode): number | string
+  showToaster(options: any): number | string {
+    return showReactToaster(options)
+  }
+
+  /**
+   * Closes the toaster with the specified id.
+   * @param id the id of the toaster to close.
+   */
+  closeToaster = closeReactToaster
+}
+
+/**
+ * Manages overlay components of the layout like: modal, rightPanel, bottomDialog and toaster.
+ */
+export const overlay = new LayoutOverlayManager()