@stack-spot/portal-layout 0.0.64 → 1.0.0-dev.1768482785050

package/src/LayoutOverlayManager.tsx

@@ -1,38 +1,104 @@
 /* eslint-disable react-hooks/rules-of-hooks */
 
 import { Button } from '@citric/core'
+import { ModalContent } from '@citric/ui'
+import { focusAccessibleElement, focusFirstChild } from '@stack-spot/portal-components'
+import { last } from 'lodash'
 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 { showToaster as showReactToaster } from './toaster'
-import { focusAccessibleElement, focusFirstChild, valueOfLayoutVar } from './utils'
+import { CustomToasterOptions, DefaultToasterOptions, closeReactToaster, showToaster as showReactToaster } from './toaster'
+import { CustomModalSize, ModalSize, RightPanelSize } from './types'
+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,
 }
 
+interface ModalContent {
+  id?: string,
+  element: React.ReactElement,
+  size: CustomModalSize | RightPanelSize,
+  onClose?: () => void,
+  stack: boolean,
+}
+
 type BottomDialogOptions = Omit<DialogOptions, 'title'>
-type OverlaySize = 'small' | 'medium' | 'large'
-type ModalSize = 'fit-content' | OverlaySize
-type SetContentFn = ((content: ReactElement | undefined) => void) | undefined
+type SetContentFn = (content: ModalContent[]) => void
 
 interface OverlayContentSetter {
   modal?: SetContentFn,
   rightPanel?: SetContentFn,
-  bottomDialog?: SetContentFn,
+  bottomDialog?: ((content: React.ReactElement | undefined) => void),
 }
 
 interface CustomModalOptions {
-  size?: ModalSize,
+  /**
+   * An optional, unique identifier for this modal.
+   */
+  id?: string,
+  /**
+   * The size of the modal.
+   */
+  size?: CustomModalSize,
+  /**
+   * A function to call when the modal closes. 
+   */
   onClose?: () => void,
+  /**
+   * Property that defines whether the modal should ignore the initial focus on the close button. 
+   * @default true
+   */
+  ignoreFirstFocusOnCloseButton?: boolean,
+  /**
+   * If true, instead of replacing the previously opened modal (if any), it will open on top of it (stacked).
+   * 
+   * When a modal is stacked on top of another:
+   *   - Closing the modal, closes all opened modals.
+   *   - Popping the modal, closes only the modal at the top of the stack.
+   *   - Only the modal at the top of the stack can be interacted with.
+   * 
+   * @default false
+   */
+  stack?: boolean,
 }
 
 interface CustomRightPanelOptions {
-  size?: OverlaySize,
+  /**
+   * An optional, unique identifier for this right panel.
+   */
+  id?: string,
+  /**
+   * The size of the right panel.
+   */
+  size?: RightPanelSize,
+  /**
+   * A function to call when the right panel closes. 
+   */
   onClose?: () => void,
+  /**
+   * Property that defines whether the modal should ignore the initial focus on the close button. 
+   * @default true
+   */
+  ignoreFirstFocusOnCloseButton?: boolean,
+  /**
+   * If true, instead of replacing the previously opened right panel (if any), it will open on top of it (stacked).
+   * 
+   * When a right panel is stacked on top of another:
+   *   - Closing the panel, closes all opened panels.
+   *   - Popping the panel, closes only the panel at the top of the stack.
+   *   - Only the panel at the top of the stack can be interacted with.
+   * 
+   * @default false
+   */
+  stack?: boolean,
 }
 
 function multipleCallsWarning(type: 'modal' | 'rightPanel', timeMS: number) {
@@ -48,46 +114,90 @@ 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 modals: ModalContent[] = []
+  private panels: ModalContent[] = []
+
+  private closeCustomBackdrops(elements: NodeListOf<Element>) {
+    // this is the easiest way to close each custom backdrop by calling their respective "onClose" callbacks. This is a hidden button
+    // that exists in every <Backdrop> component.
+    elements.forEach(element => (element.querySelector('[data-custom-backdrop-close]') as HTMLElement)?.click?.())
+  }
+
+  private onClickBackdrop(event: MouseEvent) {
+    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 {
+      const customBackdrops = this.getAllVisibleCustomBackdrops()
+      if (customBackdrops.length) {
+        let isClickInside = false
+        customBackdrops.forEach((element) => {
+          if (element.contains(event.target as Node)) isClickInside = true
+        })
+        if (!isClickInside) this.closeCustomBackdrops(customBackdrops)
+      } else {
+        this.setMainContentInteractivity(true)
+      }
+    }
+  }
+
+  private onPressKeyInBackdrop(event: KeyboardEvent) {
+    if (event.key !== 'Escape') return
+    if (this.isModalOpen()) this.closeModal()
+    if (this.isRightPanelOpen()) this.closeRightPanel()
+    else {
+      const customBackdrops = this.getAllVisibleCustomBackdrops()
+      if (customBackdrops.length) this.closeCustomBackdrops(customBackdrops)
+      else this.setMainContentInteractivity(true)
+    }
+    event.preventDefault()
+  }
 
   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.elements.backdrop?.addEventListener('mousedown', (event) => this.onClickBackdrop(event))
+    this.elements.backdrop?.addEventListener('keydown', (event) => this.onPressKeyInBackdrop(event))
     this.setInteractivity(this.elements?.modal, false)
     this.setInteractivity(this.elements?.rightPanel, false)
     this.setInteractivity(this.elements?.bottomDialog, false)
   }
 
-  // this should actually be like Kotlin's "internal", i.e. private to any user of the lib, but public to the lib itself.
-  // @ts-ignore
-  private useOverlays() {
+  private getAllVisibleCustomBackdrops() {
+    return document.querySelectorAll('[data-custom-backdrop-visibility=true]')
+  }
+
+  /**
+   * Setup the overlay layout elements.
+   * @returns the content for the modal, rightPanel and bottomDialog.
+   * @internal
+   */
+  useOverlays() {
     useLayoutEffect(() => {
       if (!this.elements) this.setupElements()
     }, [])
-    const [modal, setModal] = useState<ReactElement | undefined>()
-    const [rightPanel, setRightPanel] = useState<ReactElement | undefined>()
+    const [modal, setModal] = useState<ModalContent[]>([])
+    const [rightPanel, setRightPanel] = useState<ModalContent[]>([])
     const [bottomDialog, setBottomDialog] = useState<ReactElement | undefined>()
-    this.setContent.modal = setModal
-    this.setContent.rightPanel = setRightPanel
+    this.setContent.modal = (content) => {
+      this.modals = content
+      setModal(content)
+    }
+    this.setContent.rightPanel = (content) => {
+      this.panels = content
+      setRightPanel(content)
+    }
     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')
@@ -105,114 +215,273 @@ class LayoutOverlayManager {
     this.elements?.backdrop?.setAttribute('class', interactive ? '' : 'visible')
   }
 
-  private showOverlay(element: HTMLElement | null | undefined, extraClasses: string[] = [], blockMainContent = true) {
+  private showOverlay(element: HTMLElement | null | undefined,
+    extraClasses: string[] = [],
+    blockMainContent = true,
+    manageClasses = true,
+    ignoreFirstFocusOnCloseButton = true,
+  ) {
     this.lastActiveElement = document.activeElement
-    element?.classList.add('visible', ...extraClasses)
+    if (manageClasses) 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}` },
+      {
+        priority: [['input', 'textarea', 'select', 'other', 'button']] as const,
+        ...(ignoreFirstFocusOnCloseButton ? { ignore: `#${CLOSE_OVERLAY_ID}` } : {}),
+      },
     ), 50)
   }
 
-  private hideOverlay(element: HTMLElement | null | undefined) {
-    element?.setAttribute('class', '')
+  private hideOverlay(element: HTMLElement | null | undefined, manageClasses = true) {
+    if (manageClasses) element?.setAttribute('class', '')
     this.setInteractivity(element, false)
     this.setMainContentInteractivity(true)
   }
 
+  /**
+   * Shows the backdrop. The element passed as parameter must be a child of backdrop. Some accessibility features will be attached to
+   * the element.
+   * 
+   * Consider using the component <Backdrop> from this library instead of calling this function directly.
+   * @param element the element to show inside the backdrop. It must already be a child of the backdrop.
+   */
+  showBackdrop(element?: HTMLElement | null) {
+    this.showOverlay(element, [], true, false)
+  }
+
+  /**
+   * Closes the backdrop. The element passed as parameter must be a child of backdrop. Some accessibility features will be run on the
+   * element.
+   * 
+   * Consider using the component <Backdrop> from this library instead of calling this function directly.
+   * @param element the element showing inside the backdrop. It must be a child of the backdrop.
+   */
+  closeBackdrop(element?: HTMLElement | null) {
+    this.hideOverlay(element, false)
+    const lastActiveElement = this.lastActiveElement as HTMLElement | null
+    lastActiveElement?.focus?.()
+  }
+
+  /**
+   * @returns true if the modal is currently opened. False otherwise.
+   */
   isModalOpen() {
     return this.elements?.modal?.classList.contains('visible') ?? false
   }
 
+  /**
+   * @returns the number of modals currently tracked.
+   */
+  getNumberOfOpenModals() {
+    return this.modals.length
+  }
+
+  /**
+   * @returns the number of right panels currently tracked.
+   */
+  getNumberOfOpenRightPanels() {
+    return this.panels.length
+  }
+
+  /**
+   * @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
   }
 
-  showCustomModal(content: React.ReactElement, { size = 'medium', onClose }: CustomModalOptions = {}) {
+  /**
+   * 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, ignoreFirstFocusOnCloseButton = true, stack = false, id }: 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])
+    const modal = { element: content, onClose, size, stack, id }
+    const currentModalSize = last(this.modals)?.size
+    this.setContent.modal(stack ? [...this.modals, modal] : [modal])
+    // we should remove the previous size, if any, before showing the modal
+    if (currentModalSize) this.elements.modal.classList.remove(currentModalSize)
+    this.showOverlay(this.elements.modal, [size], true, true, ignoreFirstFocusOnCloseButton)
   }
 
-  showModal({ size, ...props }: OverlayContentProps & { size?: ModalSize }) {
-    this.showCustomModal(<OverlayContent {...props} onClose={() => this.closeModal()} type="modal" />, { size, onClose: props.onClose })
+  /**
+   * 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, ignoreFirstFocusOnCloseButton, stack, onGoBack, id, ...props
+  }: OverlayContentProps & { size?: ModalSize } & Pick<CustomModalOptions, 'ignoreFirstFocusOnCloseButton' | 'stack' | 'id'>) {
+    const handleBack = onGoBack ?? ((stack && this.modals.length >= 1) ? () => this.popModal() : undefined)
+    this.showCustomModal(
+      <OverlayContent {...props} onGoBack={handleBack} onClose={() => this.closeModal()} type="modal" />,
+      { size, onClose: props.onClose, ignoreFirstFocusOnCloseButton, stack, id },
+    )
   }
 
-  private showDialog(options: DialogOptions): Promise<boolean> {
+  private showDialog({ ignoreFirstFocusOnCloseButton = false, options, size = 'small' }:
+    { ignoreFirstFocusOnCloseButton?: boolean, size?: CustomModalSize, 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) },
-        )
+        if (options.type === 'panel') {
+          this.showCustomRightPanel(
+            <Dialog
+              {...options}
+              onCancel={() => this.closeModal()}
+              onConfirm={() => {
+                dialogResult = true
+                this.closeModal()
+              }}
+            />,
+            { size: size as RightPanelSize, onClose: () => resolve(dialogResult) },
+          )
+        } else {
+          this.showCustomModal(
+            <Dialog
+              {...options}
+              onCancel={() => this.closeModal()}
+              onConfirm={() => {
+                dialogResult = true
+                this.closeModal()
+              }}
+            />,
+            { size, onClose: () => resolve(dialogResult), ignoreFirstFocusOnCloseButton },
+          )
+        }
       } catch (error) {
         reject(error)
       }
     })
   }
 
-  confirm({ confirm, cancel, ...options }: DialogOptions): Promise<boolean> {
+  /**
+   * 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 and its size: {@link DialogOptions}.
+   * @returns a promise that resolves with the user's answer.
+   */
+  confirm({ confirm, cancel, size, ...options }: DialogOptions & { size?: CustomModalSize }): Promise<boolean> {
     const t = getDictionary()
-    return this.showDialog({ ...options, confirm: confirm || t.confirm, cancel: cancel || t.cancel })
+    return this.showDialog({
+      ignoreFirstFocusOnCloseButton: !!options.validation,
+      size,
+      options: {
+        ...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 })
+    await this.showDialog({
+      ignoreFirstFocusOnCloseButton: !!options.validation,
+      options: {
+        ...options,
+        confirm: showButton ? (confirm || t.confirm) : undefined,
+      },
+    })
   }
 
-  showBottomDialog({ message, cancel, confirm }: BottomDialogOptions): Promise<boolean> {
+  /**
+   * 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?.(
         <>
-          {message}
+          {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)
+      this.showOverlay(this.elements?.bottomDialog, undefined, false, true, true)
     })
   }
 
-  showCustomRightPanel(content: ReactElement, { size = 'medium', onClose }: CustomRightPanelOptions = {}) {
+  /**
+   * 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, ignoreFirstFocusOnCloseButton = true, stack = false, id }:
+    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)
+    const panel = { element: content, onClose, size, stack, id }
+    const currentPanelSize = last(this.modals)?.size
+    this.setContent.rightPanel(stack ? [...this.panels, panel] : [panel])
+    // we should remove the previous size, if any, before showing the panel
+    if (currentPanelSize) this.elements.rightPanel.classList.remove(currentPanelSize)
     setTimeout(() => {
-      this.showOverlay(this.elements?.rightPanel)
+      this.showOverlay(this.elements?.rightPanel, [size], true, true, ignoreFirstFocusOnCloseButton)
     })
   }
 
-  showRightPanel({ size, ...props }: OverlayContentProps & { size?: OverlaySize }) {
+  /**
+   * 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, ignoreFirstFocusOnCloseButton, stack, onGoBack, id, ...props }:
+    OverlayContentProps & Pick<CustomRightPanelOptions, 'size' | 'ignoreFirstFocusOnCloseButton' | 'stack' | 'id'>) {
+    const handleBack = onGoBack ?? ((stack && this.panels.length >= 1) ? () => this.popRightPanel() : undefined)
     this.showCustomRightPanel(
-      <OverlayContent {...props} onClose={() => this.closeRightPanel()} type="panel" />,
-      { size, onClose: props.onClose },
+      <OverlayContent {...props} onGoBack={handleBack} onClose={() => this.closeRightPanel()} type="panel" />,
+      { size, onClose: props.onClose, ignoreFirstFocusOnCloseButton, stack, id },
     )
   }
 
-  /**
+  /*
    * 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.
    */
@@ -221,69 +490,214 @@ class LayoutOverlayManager {
     this.lastActiveElement = null
   }
 
+  /**
+   * Closes all opened modals.
+   * @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 shouldHideBackdrop = this.panels.length === 0
+    if (shouldHideBackdrop) this.elements?.backdrop?.setAttribute('class', '')
+    if (runCloseListener) {
+      this.modals.forEach((modal) => {
+        const onClose = modal.onClose
+        // setting it to undefined before running it prevents nested calls to closeModal from generating infinite loops.
+        modal.onClose = undefined
+        onClose?.()
+      })
     }
     const animationMS = parseFloat(valueOfLayoutVar('--modal-animation-duration')) * 1000
     setTimeout(
       () => {
-        if (this.elements?.backdrop?.classList.contains('visible')) {
+        if (shouldHideBackdrop && 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)
+        if (this.setContent.modal) this.setContent.modal([])
+        if (shouldHideBackdrop) this.hideOverlay(this.elements?.modal)
         this.focusLastActiveElement()
       },
       animationMS,
     )
   }
 
+  /**
+   * Closes the top-most modal in the stack. Will behave like `closeModal` if only a single modal exists in the stack.
+   * @param amount number of modals to pop. Defaults to 1.
+   * @param runCloseListener whether or not to run the function `onClose` passed to `showModal` or `showCustomModal`. Defaults to true.
+   */
+  popModal(amount = 1, runCloseListener = true) {
+    if (amount <= 0) return
+    if (this.modals.length <= amount) return this.closeModal(runCloseListener)
+    for (let i = 0; i < amount; i++) {
+      const modalToClose = this.modals.pop()! // "!": because of the second "if", the array can't have less than "amount + 1" elements
+      if (runCloseListener) modalToClose.onClose?.()
+      this.elements?.modal?.classList.remove(modalToClose.size)
+    }
+    const topModal = last(this.modals)!  // "!": because of the second "if", the array can't have less than "amount + 1" elements
+    this.elements?.modal?.classList.add(topModal.size)
+    this.setContent.modal?.([...this.modals])
+  }
+
+  /**
+   * Close all modals in the stack of modal until the modal with the given id is found. If no modal with the given id is found, nothing
+   * happens.
+   * @param id the id of the modal to pop to.
+   * @param inclusive when true, the modal with the given id is also popped. Defaults to false.
+   */
+  popModalTo(id: string, inclusive = false) {
+    const index = this.modals.findIndex(m => m.id === id)
+    if (index >= 0) this.popModal(this.modals.length - index - (inclusive ? 0 : 1))
+  }
+
+  /**
+   * Closes all opened right panels.
+   * @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 shouldHideBackdrop = this.modals.length === 0
+    if (shouldHideBackdrop) this.elements?.backdrop?.setAttribute('class', '')
+    if (runCloseListener) {
+      this.panels.forEach((panel) => {
+        const onClose = panel.onClose
+        // setting it to undefined before running it prevents nested calls to closeRightPanel from generating infinite loops.
+        panel.onClose = undefined
+        onClose?.()
+      })
     }
     const animationMS = parseFloat(valueOfLayoutVar('--right-panel-animation-duration')) * 1000
     setTimeout(
       () => {
-        if (this.elements?.backdrop?.classList.contains('visible')) {
+        if (shouldHideBackdrop && 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)
+        if (this.setContent.rightPanel) this.setContent.rightPanel([])
+        if (shouldHideBackdrop) this.hideOverlay(this.elements?.rightPanel)
         this.focusLastActiveElement()
       },
       animationMS,
     )
   }
 
+  /**
+   * Closes the top-most modal in the stack. Will behave like `closeModal` if only a single modal exists in the stack.
+   * @param runCloseListener whether or not to run the function `onClose` passed to `showModal` or `showCustomModal`. Defaults to true.
+   */
+  popRightPanel(amount = 1, runCloseListener = true) {
+    if (amount <= 0) return
+    if (this.panels.length <= amount) return this.closeRightPanel(runCloseListener)
+    for (let i = 0; i < amount; i++) {
+      const panelToClose = this.panels.pop()! // "!": because of the second "if", the array can't have less than "amount + 1" elements
+      if (runCloseListener) panelToClose.onClose?.()
+      this.elements?.rightPanel?.classList.remove(panelToClose.size)
+    }
+    const topPanel = last(this.panels)!  // "!": because of the second "if", the array can't have less than "amount + 1" elements
+    this.elements?.rightPanel?.classList.add(topPanel.size)
+    this.setContent.rightPanel?.([...this.panels])
+  }
+
+  /**
+   * Close all right panels in the stack of panels until the panel with the given id is found. If no panel with the given id is found,
+   * nothing happens.
+   * @param id the id of the right panel to pop to.
+   * @param inclusive when true, the right panel with the given id is also popped. Defaults to false.
+   */
+  popRightPanelTo(id: string, inclusive = false) {
+    const index = this.panels.findIndex(m => m.id === id)
+    if (index >= 0) this.popRightPanel(this.panels.length - index - (inclusive ? 0 : 1))
+  }
+
+  /**
+   * 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)
   }
 
-  showToaster = showReactToaster
+  /**
+   * 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()