@stack-spot/citric-react 0.27.2 → 0.29.0

package/src/components/Link.tsx

@@ -11,14 +11,14 @@ export interface BaseLinkProps extends WithColor {
    */
   appearance?: TextAppearance,
   /**
-   * Whether or not a click in this link should generate analytics data.
+   * Metadata for the general onClick event, set by the CitricController. Useful for creating analytics data.
    * 
-   * This only takes effect if there's a CitricController in React's context. The value of `analytics` is passed to the function
+   * This only takes effect if there's a CitricController in React's context. The value of `metadata` is passed to the function
    * `onClickLink` of the controller.
    * 
    * @default false
    */
-  analytics?: boolean,
+  metadata?: any,
 }
 
 export type LinkProps = React.JSX.IntrinsicElements['a'] & BaseLinkProps
@@ -27,9 +27,9 @@ export type LinkProps = React.JSX.IntrinsicElements['a'] & BaseLinkProps
  * Renders an html anchor by default, the actual component to render may be set on a CitricController, through the function `renderLink`.
  * 
  * Whenever a link is clicked, the function `onClickLink` of the nearest CitricController is called with the event and the value of the
- * prop `analytics`.
+ * prop `metadata`.
  */
-export const Link = withRef(({ appearance, color, style, className, children, onClick, analytics, ...props }: LinkProps) => {
+export const Link = withRef(({ appearance, color, style, className, children, onClick, metadata, ...props }: LinkProps) => {
   const citric = useCitricController()
   const linkProps = {
     component: 'link',
@@ -37,7 +37,7 @@ export const Link = withRef(({ appearance, color, style, className, children, on
     className: applyTextAppearance(className, appearance),
     onClick: (e: React.MouseEvent<HTMLAnchorElement>) => {
       onClick?.(e)
-      citric?.onClickLink?.(e, analytics ?? false)
+      citric?.onClickLink?.(e, metadata ?? false)
     },
     ...props,
   } as const

package/src/components/Overlay/index.tsx

@@ -44,6 +44,7 @@ export function Overlay<T extends keyof HTMLTag>({
   content,
   position = 'top',
   triggerOn = 'hover',
+  alignment = 'center',
   attributes,
   onRenderChild,
   autoFocusBehavior = 'keyboard',
@@ -53,11 +54,11 @@ export function Overlay<T extends keyof HTMLTag>({
   const controller = useRef<OverlayController>({ close: () => Promise.resolve() })
   const wrapper = useRef<HTMLDivElement | null>(null)
   // props that don't require removing and reattaching the event listeners
-  const dynamic = useRef({ tag, content, position, attributes })
+  const dynamic = useRef({ tag, content, position, alignment, attributes })
 
   useEffect(() => {
-    dynamic.current = { tag, content, position, attributes }
-  }, [tag, content, position, attributes])
+    dynamic.current = { tag, content, position, alignment, attributes }
+  }, [tag, content, position, alignment, attributes])
 
   useEffect(() => {
     let visible = false
@@ -88,6 +89,7 @@ export function Overlay<T extends keyof HTMLTag>({
           : <OverlayProvider value={controller.current}>{dynamic.current.content}</OverlayProvider>,
         target,
         position: dynamic.current.position,
+        alignment: dynamic.current.alignment,
         attributes: dynamic.current.attributes,
       })
       hideOverlay = hideFn

package/src/components/Select/MultiSelect.tsx

@@ -134,9 +134,8 @@ export const MultiSelect = withRef(
         {...props}
       >
         <header
-          onClick={(e) => {
+          onClick={() => {
             if (disabled) return
-            if (!open) e.stopPropagation()
             setFocused(true)
             setOpen(true)
           }}

package/src/components/Select/RichSelect.tsx

@@ -92,9 +92,8 @@ export const RichSelect = withRef(
           wrap={false}
         />
         <header
-          onClick={(e) => {
+          onClick={() => {
             if (disabled) return
-            if (!open) e.stopPropagation()
             setFocused(true)
             setOpen(true)
           }}

package/src/overlay.ts

@@ -38,8 +38,6 @@ export interface OverlayOptions<T extends keyof HTMLTag> {
    */
   position?: RelativePosition,
   /**
-   * TODO: implement this.
-   * 
    * 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.
    * 
@@ -72,7 +70,7 @@ interface PositionWithRelativeData extends Position {
   relativeTo: RelativePosition,
 }
 
-type CalculatePosOptions = Pick<Required<OverlayOptions<any>>, 'position' | 'target' | 'reference'>
+type CalculatePosOptions = Pick<Required<OverlayOptions<any>>, 'position' | 'target' | 'reference' | 'alignment'>
   & { overlay: HTMLElement }
 
 const animationDurationMS = 300
@@ -82,11 +80,28 @@ function hasMargins(element: HTMLElement) {
   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)) {
@@ -111,18 +126,18 @@ function calculatePosition({
     switch (relativePosition) {
       case 'top':
         referencePosition.top = elementDimensions.top + window.scrollY
-        referencePosition.left = elementDimensions.left + elementDimensions.width / 2 + window.scrollX
+        referencePosition.left = calculateAlignment(alignment, elementDimensions.left, elementDimensions.width, window.scrollX)
         break
       case 'bottom':
         referencePosition.top = elementDimensions.bottom + window.scrollY
-        referencePosition.left = elementDimensions.left + elementDimensions.width / 2 + window.scrollX
+        referencePosition.left = calculateAlignment(alignment, elementDimensions.left, elementDimensions.width, window.scrollX)
         break
       case 'left':
-        referencePosition.top = elementDimensions.top + elementDimensions.height / 2 + window.scrollY
+        referencePosition.top = calculateAlignment(alignment, elementDimensions.top, elementDimensions.height, window.scrollY)
         referencePosition.left = elementDimensions.left + window.scrollX
         break
       case 'right':
-        referencePosition.top = elementDimensions.top + elementDimensions.height / 2 + window.scrollY
+        referencePosition.top = calculateAlignment(alignment, elementDimensions.top, elementDimensions.height, window.scrollY)
         referencePosition.left = elementDimensions.right + window.scrollX
     }
   }
@@ -130,17 +145,17 @@ function calculatePosition({
   switch (relativePosition) {
     case 'top':
       position.top -= overlayDimensions.height
-      position.left -= overlayDimensions.width / 2
+      position.left -= calculateAlignmentOffset(alignment, overlayDimensions.width)
       break
     case 'bottom':
-      position.left -= overlayDimensions.width / 2
+      position.left -= calculateAlignmentOffset(alignment, overlayDimensions.width)
       break
     case 'left':
-      position.top -= overlayDimensions.height / 2
+      position.top -= calculateAlignmentOffset(alignment, overlayDimensions.height)
       position.left -= overlayDimensions.width
       break
     case 'right':
-      position.top -= overlayDimensions.height / 2
+      position.top -= calculateAlignmentOffset(alignment, overlayDimensions.height)
   }
   return position
 }
@@ -210,6 +225,47 @@ function setElementAttributes(element: HTMLElement, attributes: Record<string, a
   }
 }
 
+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.
@@ -219,8 +275,9 @@ function setElementAttributes(element: HTMLElement, attributes: Record<string, a
  * @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', attributes }: OverlayOptions<T>,
+  { 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
@@ -238,15 +295,30 @@ export function showOverlay<T extends keyof HTMLTag = 'div'>(
       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(
-      { overlay, reference, target },
+      { 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)
+    overlay.classList.add(overlayPos.relativeTo, `align-${alignment}`)
+    removeScrollEffects = attachScrollEffects(target, overlay, hide)
   }, 0)
   
   return {
@@ -258,17 +330,7 @@ export function showOverlay<T extends keyof HTMLTag = 'div'>(
      * Removes the overlay element.
      * @returns a promise that completes when the element is fully removed (after any animation).
      */
-    hide: () => new Promise<void>((resolve) => {
-      overlay.style.opacity = '0'
-      overlay.style.pointerEvents = 'none'
-      overlay.inert = true
-      setTimeout(() => {
-        try {
-          unmount()
-        } catch { /* empty */ }
-        resolve()
-      }, animationDurationMS)
-    }),
+    hide,
     /**
      * Returns a promise that resolves as soon as the overlay finishes the animation to show up.
      */

package/src/types.ts

@@ -180,15 +180,15 @@ export interface CitricController {
   /**
    * A function to run whenever the component Button is clicked.
    * @param event the click event.
-   * @param analytics true if analytics are enabled for this button, false otherwise.
+   * @param metadata metadata of the button.
    */
-  onClickButton?: (event: React.MouseEvent<HTMLButtonElement>, analytics: boolean) => void,
+  onClickButton?: (event: React.MouseEvent<HTMLButtonElement>, metadata: any) => void,
   /**
    * A function to run whenever the component Link is clicked.
    * @param event the click event.
-   * @param analytics true if analytics are enabled for this link, false otherwise.
+   * @param metadata metadata of the anchor.
    */
-  onClickLink?: (event: React.MouseEvent<HTMLAnchorElement>, analytics: boolean) => void,
+  onClickLink?: (event: React.MouseEvent<HTMLAnchorElement>, metadata: any) => void,
   /**
    * A custom renderer for error feedbacks.
    *