@stack-spot/citric-react 0.37.1 → 0.39.0

package/src/overlay.ts

@@ -1,341 +1,341 @@
-import { createRoot } from 'react-dom/client'
-import { HTMLTag, WithDataAttributes } from './types'
-import { styleObjectToCssString } from './utils/css'
-
-export type RelativePosition = 'top' | 'bottom' | 'left' | 'right'
-
-export interface OverlayOptions<T extends keyof HTMLTag> {
-  /**
-   * The tag to render when creating the overlay element.
-   * 
-   * @default 'div'
-   */
-  tag?: T,
-  /**
-   * The content of the overlay element.
-   * 
-   * When this is a string, a number or a boolean, the content will be appended to the overlay element. Otherwise, a new React concurrent
-   * instance will be created to render the React tree node inside the overlay element.
-   */
-  content: React.ReactNode,
-  /**
-   * Which element will be used as a reference to position the overlay element.
-   * This can be either an HTMLElement or an event. If this is a event, the element in `event.target` will be used unless `reference` is
-   * set to `'mouse'`, in this case, the reference will be the current cursor position.
-   */
-  target: Event | HTMLElement,
-  /**
-   * Takes effect when `target` is a MouseEvent. If this is set to `'mouse'`, then the position to be used as a reference to place the
-   * overlay will be the current cursor position.
-   * 
-   * @default 'element'
-   */
-  reference?: 'element' | 'mouse',
-  /**
-   * Where, relative to `target`, should we place the overlay?
-   * 
-   * @default 'top'
-   */
-  position?: RelativePosition,
-  /**
-   * Affects the positioning of the overlay relative to `target`. While `position` defines the overlay position in the main axis,
-   * `alignment` defines the position in the cross axis.
-   * 
-   * @default 'center'
-   */
-  alignment?: 'start' | 'center' | 'end',
-  /**
-   * TODO: implement this (currently, only 'fade' works).
-   * 
-   * - fade: the overlay fades in to appear and fades out to disappear.
-   * - accordion: the element grows to appear and shrinks to disappear. The direction of the growth depends on `position`.
-   * - bubble: grows from scale(0) to scale(1) from its center to appear. Shrinks from scale(1) to scale(0) to disappear.
-   * - none: no animation is used.
-   * 
-   * @default 'fade'
-   */
-  animation?: 'fade' | 'accordion' | 'bubble' | 'none',
-  /**
-   * The attributes for the HTMLElement that will be created for the overlay.
-   */
-  attributes?: JSX.IntrinsicElements[T] & WithDataAttributes & { inert?: boolean },
-}
-
-interface Position {
-  top: number,
-  left: number,
-}
-
-interface PositionWithRelativeData extends Position {
-  relativeTo: RelativePosition,
-}
-
-type CalculatePosOptions = Pick<Required<OverlayOptions<any>>, 'position' | 'target' | 'reference' | 'alignment'>
-  & { overlay: HTMLElement }
-
-const animationDurationMS = 300
-
-function hasMargins(element: HTMLElement) {
-  const s = element.style
-  return s.margin || s.marginTop || s.marginBottom || s.marginLeft || s.marginRight
-}
-
-function calculateAlignment(alignment: CalculatePosOptions['alignment'], offset: number, size: number, scroll: number) {
-  switch (alignment) {
-    case 'center': return offset + size / 2 + scroll
-    case 'end': return offset + size + scroll
-    case 'start': return offset + scroll
-  }
-}
-
-function calculateAlignmentOffset(alignment: CalculatePosOptions['alignment'], overlaySize: number) {
-  switch (alignment) {
-    case 'center': return overlaySize / 2
-    case 'end': return overlaySize
-    case 'start': return 0
-  }
-} 
-
-function calculatePosition({
-  overlay,
-  reference,
-  target,
-  position: relativePosition,
-  alignment,
-}: CalculatePosOptions): Position & { overlayWidth: number, overlayHeight: number } {
-  const overlayDimensions = overlay.getBoundingClientRect()
-  if (hasMargins(overlay)) {
-    const style = overlay.computedStyleMap()
-    const mt = parseInt(style.get('margin-top')?.toString() ?? '0')
-    const mb = parseInt(style.get('margin-bottom')?.toString() ?? '0')
-    const ml = parseInt(style.get('margin-left')?.toString() ?? '0')
-    const mr = parseInt(style.get('margin-right')?.toString() ?? '0')
-    if (mt) overlayDimensions.height += mt
-    if (mb) overlayDimensions.height += mb
-    if (ml) overlayDimensions.width += ml
-    if (mr) overlayDimensions.width += mr
-  }
-  const referencePosition = { top: 0, left: 0, overlayWidth: overlayDimensions.width, overlayHeight: overlayDimensions.height }
-  if (reference === 'mouse' && target instanceof MouseEvent) {
-    referencePosition.top = target.clientY
-    referencePosition.left = target.clientX
-  } else {
-    const element = target instanceof Event ? target.target : target
-    if (!(element instanceof HTMLElement)) return referencePosition
-    const elementDimensions = element.getBoundingClientRect()
-    switch (relativePosition) {
-      case 'top':
-        referencePosition.top = elementDimensions.top + window.scrollY
-        referencePosition.left = calculateAlignment(alignment, elementDimensions.left, elementDimensions.width, window.scrollX)
-        break
-      case 'bottom':
-        referencePosition.top = elementDimensions.bottom + window.scrollY
-        referencePosition.left = calculateAlignment(alignment, elementDimensions.left, elementDimensions.width, window.scrollX)
-        break
-      case 'left':
-        referencePosition.top = calculateAlignment(alignment, elementDimensions.top, elementDimensions.height, window.scrollY)
-        referencePosition.left = elementDimensions.left + window.scrollX
-        break
-      case 'right':
-        referencePosition.top = calculateAlignment(alignment, elementDimensions.top, elementDimensions.height, window.scrollY)
-        referencePosition.left = elementDimensions.right + window.scrollX
-    }
-  }
-  const position = { ...referencePosition }
-  switch (relativePosition) {
-    case 'top':
-      position.top -= overlayDimensions.height
-      position.left -= calculateAlignmentOffset(alignment, overlayDimensions.width)
-      break
-    case 'bottom':
-      position.left -= calculateAlignmentOffset(alignment, overlayDimensions.width)
-      break
-    case 'left':
-      position.top -= calculateAlignmentOffset(alignment, overlayDimensions.height)
-      position.left -= overlayDimensions.width
-      break
-    case 'right':
-      position.top -= calculateAlignmentOffset(alignment, overlayDimensions.height)
-  }
-  return position
-}
-
-function getSafeOverlayPosition(
-  options: Omit<CalculatePosOptions, 'position'>, positionPriority: RelativePosition[], fallback?: PositionWithRelativeData,
-): PositionWithRelativeData {
-  if (!positionPriority.length) return fallback ?? { top: 0, left: 0, relativeTo: 'top' }
-  const [relativePosition, ...remainingRelativePositions] = positionPriority
-  const position = { ...calculatePosition({ ...options, position: relativePosition }), relativeTo: relativePosition }
-  switch (relativePosition) {
-    case 'top':
-      if (position.left < 0) position.left = 0
-      if (position.left + position.overlayWidth > document.body.clientWidth) {
-        position.left = document.body.clientWidth - position.overlayWidth
-      }
-      if (position.top < 0) return getSafeOverlayPosition(options, remainingRelativePositions, fallback ?? position)
-      break
-    case 'bottom':
-      if (position.left < 0) position.left = 0
-      if (position.left + position.overlayWidth > document.body.clientWidth) {
-        position.left = document.body.clientWidth - position.overlayWidth
-      }
-      if (position.top + position.overlayHeight > document.body.clientHeight) {
-        return getSafeOverlayPosition(options, remainingRelativePositions, fallback ?? position)
-      }
-      break
-    case 'left':
-      if (position.top < 0) position.top = 0
-      if (position.top + position.overlayHeight > document.body.clientHeight) {
-        position.top = document.body.clientHeight - position.overlayHeight
-      }
-      if (position.left < 0) return getSafeOverlayPosition(options, remainingRelativePositions, fallback ?? position)
-      break
-    case 'right':
-      if (position.top < 0) position.top = 0
-      if (position.top + position.overlayHeight > document.body.clientHeight) {
-        position.top = document.body.clientHeight - position.overlayHeight
-      }
-      if (position.left + position.overlayWidth > document.body.clientWidth) {
-        return getSafeOverlayPosition(options, remainingRelativePositions, fallback ?? position)
-      }
-  }
-  return position
-}
-
-function invert(position: RelativePosition): RelativePosition {
-  switch (position) {
-    case 'bottom': return 'top'
-    case 'top': return 'bottom'
-    case 'left': return 'right'
-    case 'right': return 'left'
-  }
-}
-
-function oppositeAxis(position: RelativePosition): [RelativePosition, RelativePosition] {
-  return (position === 'top' || position === 'bottom') ? ['left', 'right'] : ['top', 'bottom']
-}
-
-function reactAttributeToHTML(attribute: string) {
-  return attribute === 'className' ? 'class' : attribute
-}
-
-function setElementAttributes(element: HTMLElement, attributes: Record<string, any> | undefined, ignore: string[] = []) {
-  for (const attr in attributes) {
-    if (attributes[attr] !== undefined && !ignore.includes(attr)) element.setAttribute(reactAttributeToHTML(attr), attributes[attr])
-  }
-}
-
-function getClosestScrollable(element: HTMLElement, limit: HTMLElement = document.body): HTMLElement | null | undefined {
-  if (element === limit) return
-  return element.clientHeight === element.scrollHeight ? getClosestScrollable(element.parentElement!, limit) : element
-}
-
-function isElementVisible(element: HTMLElement, scrollable: HTMLElement) {
-  const elementRect = element.getBoundingClientRect()
-  const scrollableRect = scrollable.getBoundingClientRect()
-  const diffX = elementRect.left - scrollableRect.left + scrollable.scrollLeft
-  const isVisibleX = diffX + elementRect.width <= scrollable.scrollLeft + scrollableRect.width &&
-    diffX >= scrollable.scrollLeft
-  const diffY = elementRect.top - scrollableRect.top + scrollable.scrollTop
-  const isVisibleY = diffY + elementRect.height <= scrollable.scrollTop + scrollableRect.height &&
-    diffY >= scrollable.scrollTop
-  return isVisibleX && isVisibleY
-}
-
-/**
- * The tooltip may be inside a scrollable element. If this is the case, we must update its position whenever the container is scrolled.
- * If the container is scrolled enough to hide the element that triggered the overlay, we hide the overlay.
- */
-function attachScrollEffects(target: OverlayOptions<any>['target'], overlay: HTMLElement, hide: () => void) {
-  const element = target instanceof Event ? target.target as HTMLElement : target
-  const closestScrollableFromTarget = getClosestScrollable(element, overlay.parentNode as HTMLElement)
-  if (closestScrollableFromTarget) {
-    let lastScrollX = closestScrollableFromTarget.scrollLeft
-    let lastScrollY = closestScrollableFromTarget.scrollTop
-    const updatePosition = () => {
-      if (!isElementVisible(element, closestScrollableFromTarget)) return hide()
-      const diffX = closestScrollableFromTarget.scrollLeft - lastScrollX
-      const diffY = closestScrollableFromTarget.scrollTop - lastScrollY
-      overlay.style.left = `${parseInt(overlay.style.left) - diffX}px`
-      overlay.style.top = `${parseInt(overlay.style.top) - diffY}px`
-      lastScrollX = closestScrollableFromTarget.scrollLeft
-      lastScrollY = closestScrollableFromTarget.scrollTop
-    }
-    closestScrollableFromTarget.addEventListener('scroll', updatePosition)
-    return () => closestScrollableFromTarget.removeEventListener('scroll', updatePosition)
-  }
-}
-
-/**
- * Appends a new HTML Element to the tag "body". This element is absolutely positioned and its position is calculated according to the
- * options passed as parameter.
- * 
- * This function returns both the newly created HTML Element and a function to remove it.
- * @param options {@link OverlayOptions}.
- * @returns an object with two keys: "overlay" (the HTML Element created) and "hide" (a function to remove the element from the document).
- */
-export function showOverlay<T extends keyof HTMLTag = 'div'>(
-  { tag, content, target, reference = 'element', position = 'top', alignment = 'center', attributes }: OverlayOptions<T>,
-) {
-  let removeScrollEffects: (() => void) | undefined
-  const overlay = document.createElement(tag || 'div')
-  overlay.style = `z-index: 9999; pointer-events: none; position: absolute; opacity: 0; transition: opacity ${animationDurationMS / 1000}s; ${styleObjectToCssString(attributes?.style)}`
-  overlay.inert = true
-  setElementAttributes(overlay, attributes, ['style', 'inert'])
-  document.body.append(overlay)
-  let unmount: (() => void) | undefined
-  if (['string', 'number', 'boolean'].includes(typeof content)) {
-    overlay.append(`${content}`)
-    unmount = () => document.body.removeChild(overlay)
-  } else {
-    const root = createRoot(overlay)
-    root.render(content)
-    unmount = () => {
-      root.unmount()
-      document.body.removeChild(overlay)
-    }
-  }
-
-  const hide = () => new Promise<void>((resolve) => {
-    overlay.style.opacity = '0'
-    overlay.style.pointerEvents = 'none'
-    overlay.inert = true
-    setTimeout(() => {
-      try {
-        removeScrollEffects?.()
-        unmount()
-      } catch { /* empty */ }
-      resolve()
-    }, animationDurationMS)
-  })
-
-  setTimeout(() => {
-    const overlayPos = getSafeOverlayPosition(
-      { alignment, overlay, reference, target },
-      [position, invert(position), ...oppositeAxis(position)],
-    )
-    overlay.style = `z-index: 9999; position: absolute; opacity: 1; transition: opacity ${animationDurationMS / 1000}s; top: ${overlayPos.top}px; left: ${overlayPos.left}px; ${styleObjectToCssString(attributes?.style)}`
-    if (attributes && 'inert' in attributes && attributes.inert) overlay.style.pointerEvents = 'none'
-    else overlay.inert = false
-    overlay.classList.add(overlayPos.relativeTo, `align-${alignment}`)
-    removeScrollEffects = attachScrollEffects(target, overlay, hide)
-  }, 0)
-  
-  return {
-    /**
-     * The overlay element created.
-     */
-    overlay,
-    /**
-     * Removes the overlay element.
-     * @returns a promise that completes when the element is fully removed (after any animation).
-     */
-    hide,
-    /**
-     * Returns a promise that resolves as soon as the overlay finishes the animation to show up.
-     */
-    ready: new Promise<void>((resolve) => {
-      setTimeout(resolve, animationDurationMS)
-    }),
-  }
-}
+import { createRoot } from 'react-dom/client'
+import { HTMLTag, WithDataAttributes } from './types'
+import { styleObjectToCssString } from './utils/css'
+
+export type RelativePosition = 'top' | 'bottom' | 'left' | 'right'
+
+export interface OverlayOptions<T extends keyof HTMLTag> {
+  /**
+   * The tag to render when creating the overlay element.
+   * 
+   * @default 'div'
+   */
+  tag?: T,
+  /**
+   * The content of the overlay element.
+   * 
+   * When this is a string, a number or a boolean, the content will be appended to the overlay element. Otherwise, a new React concurrent
+   * instance will be created to render the React tree node inside the overlay element.
+   */
+  content: React.ReactNode,
+  /**
+   * Which element will be used as a reference to position the overlay element.
+   * This can be either an HTMLElement or an event. If this is a event, the element in `event.target` will be used unless `reference` is
+   * set to `'mouse'`, in this case, the reference will be the current cursor position.
+   */
+  target: Event | HTMLElement,
+  /**
+   * Takes effect when `target` is a MouseEvent. If this is set to `'mouse'`, then the position to be used as a reference to place the
+   * overlay will be the current cursor position.
+   * 
+   * @default 'element'
+   */
+  reference?: 'element' | 'mouse',
+  /**
+   * Where, relative to `target`, should we place the overlay?
+   * 
+   * @default 'top'
+   */
+  position?: RelativePosition,
+  /**
+   * Affects the positioning of the overlay relative to `target`. While `position` defines the overlay position in the main axis,
+   * `alignment` defines the position in the cross axis.
+   * 
+   * @default 'center'
+   */
+  alignment?: 'start' | 'center' | 'end',
+  /**
+   * TODO: implement this (currently, only 'fade' works).
+   * 
+   * - fade: the overlay fades in to appear and fades out to disappear.
+   * - accordion: the element grows to appear and shrinks to disappear. The direction of the growth depends on `position`.
+   * - bubble: grows from scale(0) to scale(1) from its center to appear. Shrinks from scale(1) to scale(0) to disappear.
+   * - none: no animation is used.
+   * 
+   * @default 'fade'
+   */
+  animation?: 'fade' | 'accordion' | 'bubble' | 'none',
+  /**
+   * The attributes for the HTMLElement that will be created for the overlay.
+   */
+  attributes?: JSX.IntrinsicElements[T] & WithDataAttributes & { inert?: boolean },
+}
+
+interface Position {
+  top: number,
+  left: number,
+}
+
+interface PositionWithRelativeData extends Position {
+  relativeTo: RelativePosition,
+}
+
+type CalculatePosOptions = Pick<Required<OverlayOptions<any>>, 'position' | 'target' | 'reference' | 'alignment'>
+  & { overlay: HTMLElement }
+
+const animationDurationMS = 300
+
+function hasMargins(element: HTMLElement) {
+  const s = element.style
+  return s.margin || s.marginTop || s.marginBottom || s.marginLeft || s.marginRight
+}
+
+function calculateAlignment(alignment: CalculatePosOptions['alignment'], offset: number, size: number, scroll: number) {
+  switch (alignment) {
+    case 'center': return offset + size / 2 + scroll
+    case 'end': return offset + size + scroll
+    case 'start': return offset + scroll
+  }
+}
+
+function calculateAlignmentOffset(alignment: CalculatePosOptions['alignment'], overlaySize: number) {
+  switch (alignment) {
+    case 'center': return overlaySize / 2
+    case 'end': return overlaySize
+    case 'start': return 0
+  }
+} 
+
+function calculatePosition({
+  overlay,
+  reference,
+  target,
+  position: relativePosition,
+  alignment,
+}: CalculatePosOptions): Position & { overlayWidth: number, overlayHeight: number } {
+  const overlayDimensions = overlay.getBoundingClientRect()
+  if (hasMargins(overlay)) {
+    const style = overlay.computedStyleMap()
+    const mt = parseInt(style.get('margin-top')?.toString() ?? '0')
+    const mb = parseInt(style.get('margin-bottom')?.toString() ?? '0')
+    const ml = parseInt(style.get('margin-left')?.toString() ?? '0')
+    const mr = parseInt(style.get('margin-right')?.toString() ?? '0')
+    if (mt) overlayDimensions.height += mt
+    if (mb) overlayDimensions.height += mb
+    if (ml) overlayDimensions.width += ml
+    if (mr) overlayDimensions.width += mr
+  }
+  const referencePosition = { top: 0, left: 0, overlayWidth: overlayDimensions.width, overlayHeight: overlayDimensions.height }
+  if (reference === 'mouse' && target instanceof MouseEvent) {
+    referencePosition.top = target.clientY
+    referencePosition.left = target.clientX
+  } else {
+    const element = target instanceof Event ? target.target : target
+    if (!(element instanceof HTMLElement)) return referencePosition
+    const elementDimensions = element.getBoundingClientRect()
+    switch (relativePosition) {
+      case 'top':
+        referencePosition.top = elementDimensions.top + window.scrollY
+        referencePosition.left = calculateAlignment(alignment, elementDimensions.left, elementDimensions.width, window.scrollX)
+        break
+      case 'bottom':
+        referencePosition.top = elementDimensions.bottom + window.scrollY
+        referencePosition.left = calculateAlignment(alignment, elementDimensions.left, elementDimensions.width, window.scrollX)
+        break
+      case 'left':
+        referencePosition.top = calculateAlignment(alignment, elementDimensions.top, elementDimensions.height, window.scrollY)
+        referencePosition.left = elementDimensions.left + window.scrollX
+        break
+      case 'right':
+        referencePosition.top = calculateAlignment(alignment, elementDimensions.top, elementDimensions.height, window.scrollY)
+        referencePosition.left = elementDimensions.right + window.scrollX
+    }
+  }
+  const position = { ...referencePosition }
+  switch (relativePosition) {
+    case 'top':
+      position.top -= overlayDimensions.height
+      position.left -= calculateAlignmentOffset(alignment, overlayDimensions.width)
+      break
+    case 'bottom':
+      position.left -= calculateAlignmentOffset(alignment, overlayDimensions.width)
+      break
+    case 'left':
+      position.top -= calculateAlignmentOffset(alignment, overlayDimensions.height)
+      position.left -= overlayDimensions.width
+      break
+    case 'right':
+      position.top -= calculateAlignmentOffset(alignment, overlayDimensions.height)
+  }
+  return position
+}
+
+function getSafeOverlayPosition(
+  options: Omit<CalculatePosOptions, 'position'>, positionPriority: RelativePosition[], fallback?: PositionWithRelativeData,
+): PositionWithRelativeData {
+  if (!positionPriority.length) return fallback ?? { top: 0, left: 0, relativeTo: 'top' }
+  const [relativePosition, ...remainingRelativePositions] = positionPriority
+  const position = { ...calculatePosition({ ...options, position: relativePosition }), relativeTo: relativePosition }
+  switch (relativePosition) {
+    case 'top':
+      if (position.left < 0) position.left = 0
+      if (position.left + position.overlayWidth > document.body.clientWidth) {
+        position.left = document.body.clientWidth - position.overlayWidth
+      }
+      if (position.top < 0) return getSafeOverlayPosition(options, remainingRelativePositions, fallback ?? position)
+      break
+    case 'bottom':
+      if (position.left < 0) position.left = 0
+      if (position.left + position.overlayWidth > document.body.clientWidth) {
+        position.left = document.body.clientWidth - position.overlayWidth
+      }
+      if (position.top + position.overlayHeight > document.body.clientHeight) {
+        return getSafeOverlayPosition(options, remainingRelativePositions, fallback ?? position)
+      }
+      break
+    case 'left':
+      if (position.top < 0) position.top = 0
+      if (position.top + position.overlayHeight > document.body.clientHeight) {
+        position.top = document.body.clientHeight - position.overlayHeight
+      }
+      if (position.left < 0) return getSafeOverlayPosition(options, remainingRelativePositions, fallback ?? position)
+      break
+    case 'right':
+      if (position.top < 0) position.top = 0
+      if (position.top + position.overlayHeight > document.body.clientHeight) {
+        position.top = document.body.clientHeight - position.overlayHeight
+      }
+      if (position.left + position.overlayWidth > document.body.clientWidth) {
+        return getSafeOverlayPosition(options, remainingRelativePositions, fallback ?? position)
+      }
+  }
+  return position
+}
+
+function invert(position: RelativePosition): RelativePosition {
+  switch (position) {
+    case 'bottom': return 'top'
+    case 'top': return 'bottom'
+    case 'left': return 'right'
+    case 'right': return 'left'
+  }
+}
+
+function oppositeAxis(position: RelativePosition): [RelativePosition, RelativePosition] {
+  return (position === 'top' || position === 'bottom') ? ['left', 'right'] : ['top', 'bottom']
+}
+
+function reactAttributeToHTML(attribute: string) {
+  return attribute === 'className' ? 'class' : attribute
+}
+
+function setElementAttributes(element: HTMLElement, attributes: Record<string, any> | undefined, ignore: string[] = []) {
+  for (const attr in attributes) {
+    if (attributes[attr] !== undefined && !ignore.includes(attr)) element.setAttribute(reactAttributeToHTML(attr), attributes[attr])
+  }
+}
+
+function getClosestScrollable(element: HTMLElement, limit: HTMLElement = document.body): HTMLElement | null | undefined {
+  if (element === limit) return
+  return element.clientHeight === element.scrollHeight ? getClosestScrollable(element.parentElement!, limit) : element
+}
+
+function isElementVisible(element: HTMLElement, scrollable: HTMLElement) {
+  const elementRect = element.getBoundingClientRect()
+  const scrollableRect = scrollable.getBoundingClientRect()
+  const diffX = elementRect.left - scrollableRect.left + scrollable.scrollLeft
+  const isVisibleX = diffX + elementRect.width <= scrollable.scrollLeft + scrollableRect.width &&
+    diffX >= scrollable.scrollLeft
+  const diffY = elementRect.top - scrollableRect.top + scrollable.scrollTop
+  const isVisibleY = diffY + elementRect.height <= scrollable.scrollTop + scrollableRect.height &&
+    diffY >= scrollable.scrollTop
+  return isVisibleX && isVisibleY
+}
+
+/**
+ * The tooltip may be inside a scrollable element. If this is the case, we must update its position whenever the container is scrolled.
+ * If the container is scrolled enough to hide the element that triggered the overlay, we hide the overlay.
+ */
+function attachScrollEffects(target: OverlayOptions<any>['target'], overlay: HTMLElement, hide: () => void) {
+  const element = target instanceof Event ? target.target as HTMLElement : target
+  const closestScrollableFromTarget = getClosestScrollable(element, overlay.parentNode as HTMLElement)
+  if (closestScrollableFromTarget) {
+    let lastScrollX = closestScrollableFromTarget.scrollLeft
+    let lastScrollY = closestScrollableFromTarget.scrollTop
+    const updatePosition = () => {
+      if (!isElementVisible(element, closestScrollableFromTarget)) return hide()
+      const diffX = closestScrollableFromTarget.scrollLeft - lastScrollX
+      const diffY = closestScrollableFromTarget.scrollTop - lastScrollY
+      overlay.style.left = `${parseInt(overlay.style.left) - diffX}px`
+      overlay.style.top = `${parseInt(overlay.style.top) - diffY}px`
+      lastScrollX = closestScrollableFromTarget.scrollLeft
+      lastScrollY = closestScrollableFromTarget.scrollTop
+    }
+    closestScrollableFromTarget.addEventListener('scroll', updatePosition)
+    return () => closestScrollableFromTarget.removeEventListener('scroll', updatePosition)
+  }
+}
+
+/**
+ * Appends a new HTML Element to the tag "body". This element is absolutely positioned and its position is calculated according to the
+ * options passed as parameter.
+ * 
+ * This function returns both the newly created HTML Element and a function to remove it.
+ * @param options {@link OverlayOptions}.
+ * @returns an object with two keys: "overlay" (the HTML Element created) and "hide" (a function to remove the element from the document).
+ */
+export function showOverlay<T extends keyof HTMLTag = 'div'>(
+  { tag, content, target, reference = 'element', position = 'top', alignment = 'center', attributes }: OverlayOptions<T>,
+) {
+  let removeScrollEffects: (() => void) | undefined
+  const overlay = document.createElement(tag || 'div')
+  overlay.style = `z-index: 9999; pointer-events: none; position: absolute; opacity: 0; transition: opacity ${animationDurationMS / 1000}s; ${styleObjectToCssString(attributes?.style)}`
+  overlay.inert = true
+  setElementAttributes(overlay, attributes, ['style', 'inert'])
+  document.body.append(overlay)
+  let unmount: (() => void) | undefined
+  if (['string', 'number', 'boolean'].includes(typeof content)) {
+    overlay.append(`${content}`)
+    unmount = () => document.body.removeChild(overlay)
+  } else {
+    const root = createRoot(overlay)
+    root.render(content)
+    unmount = () => {
+      root.unmount()
+      document.body.removeChild(overlay)
+    }
+  }
+
+  const hide = () => new Promise<void>((resolve) => {
+    overlay.style.opacity = '0'
+    overlay.style.pointerEvents = 'none'
+    overlay.inert = true
+    setTimeout(() => {
+      try {
+        removeScrollEffects?.()
+        unmount()
+      } catch { /* empty */ }
+      resolve()
+    }, animationDurationMS)
+  })
+
+  setTimeout(() => {
+    const overlayPos = getSafeOverlayPosition(
+      { alignment, overlay, reference, target },
+      [position, invert(position), ...oppositeAxis(position)],
+    )
+    overlay.style = `z-index: 9999; position: absolute; opacity: 1; transition: opacity ${animationDurationMS / 1000}s; top: ${overlayPos.top}px; left: ${overlayPos.left}px; ${styleObjectToCssString(attributes?.style)}`
+    if (attributes && 'inert' in attributes && attributes.inert) overlay.style.pointerEvents = 'none'
+    else overlay.inert = false
+    overlay.classList.add(overlayPos.relativeTo, `align-${alignment}`)
+    removeScrollEffects = attachScrollEffects(target, overlay, hide)
+  }, 0)
+  
+  return {
+    /**
+     * The overlay element created.
+     */
+    overlay,
+    /**
+     * Removes the overlay element.
+     * @returns a promise that completes when the element is fully removed (after any animation).
+     */
+    hide,
+    /**
+     * Returns a promise that resolves as soon as the overlay finishes the animation to show up.
+     */
+    ready: new Promise<void>((resolve) => {
+      setTimeout(resolve, animationDurationMS)
+    }),
+  }
+}