Updated popover and tooltip components (#74)

Author: sandra-ssh

packages/components/src/components/popover/__tests__/hooks/usePopoverInteractions.test.ts

@@ -19,9 +19,7 @@ vi.mock('@/utils/keyboard/keyboard', () => ({
 const mockOnClose = vi.fn();
 
 // Mock refs for testing
-const createMockRef = <T>(
-  initialValue: T | null = null,
-): RefObject<T | null> => ({
+const createMockRef = <T>(initialValue: T | null = null): RefObject<T> => ({
   current: initialValue,
 });
 

packages/components/src/components/popover/__tests__/popover.test.tsx

@@ -199,8 +199,8 @@ describe('Popover component', () => {
           <button>external</button>
           <Popover
             {...mockProps}
-            disableRestoreFocusAfterClose
             disableAutoFocusFirstDescendantAfterClose={false}
+            disableRestoreFocusAfterClose={true}
             open={open}
             onClose={() => setOpen(false)}
           />

packages/components/src/components/popover/__tests__/positioning/middlewareUtils.test.ts

@@ -90,6 +90,7 @@ describe('middlewareUtils', () => {
       const elementResult = getMiddlewareStack({
         arrowElement: mockArrowElement,
         edgePadding: 8,
+        enableFlip: true,
         isBodyAnchor: false,
         mainAxisOffset: 10,
         placement: 'bottom',

packages/components/src/components/popover/hooks/positioning/arrowPositionStyles.ts

@@ -96,6 +96,7 @@ export const positionArrow = (
   computedPlacement: Placement,
   offsetDistance: [number, number] | undefined,
   arrowSize: number,
+  arrowPadding?: number,
 ): void => {
   if (!hasArrow || !middlewareData.arrow || !arrowElement) {
     return;
@@ -105,7 +106,11 @@ export const positionArrow = (
 
   // Calculate arrow offset
   let arrowOffset = `-${Math.floor(arrowSize / 2)}px`;
-  if (offsetDistance && offsetDistance[0] !== undefined) {
+
+  if (arrowPadding !== undefined) {
+    // arrowPadding controls arrow offset explicitly (e.g., for HoverBridgeContainer padding)
+    arrowOffset = `${arrowPadding - Math.floor(arrowSize / 2)}px`;
+  } else if (offsetDistance && offsetDistance[0] !== undefined) {
     arrowOffset = `${-Math.abs(offsetDistance[0] / 4)}px`;
   }
 

packages/components/src/components/popover/hooks/positioning/middlewareUtils.ts

@@ -1,14 +1,16 @@
 import {
   type Middleware,
-  type Placement,
   arrow,
   flip,
   hide,
   offset,
   shift,
 } from '@floating-ui/dom';
 
-import { getPlacementDirection } from '../../utils/placement.utils';
+import {
+  type BodyDirection,
+  getPlacementDirection,
+} from '../../utils/placement.utils';
 
 /**
     },
@@ -19,8 +21,8 @@ import { getPlacementDirection } from '../../utils/placement.utils';
  * Creates middlewares for body anchor positioning
  */
 const createBodyAnchorMiddlewares = (
-  placement: Placement | undefined,
   edgePadding: number,
+  placement?: BodyDirection,
 ): Middleware[] => {
   const bodyDirection = getPlacementDirection(placement);
   const middlewares: Middleware[] = [];
@@ -57,31 +59,45 @@ const createBodyAnchorMiddlewares = (
  */
 const createElementAnchorMiddlewares = (
   mainAxisOffset: number,
-  offsetDistance: [number, number] | undefined,
   edgePadding: number,
+  offsetDistance?: [number, number],
+  enableFlip?: boolean,
 ): Middleware[] => {
   const middlewares: Middleware[] = [];
 
-  // Standard element as anchor - use offset + flip
+  // Standard element as anchor - use offset + flip + shift
   middlewares.push(
     offset({
       crossAxis: offsetDistance?.[1] || 0,
       mainAxis: mainAxisOffset,
     }),
   );
 
-  // Add flip middleware to automatically change position when necessary
-  middlewares.push(
-    flip({
-      // Provide fallback positions for better positioning
-      fallbackAxisSideDirection: 'start',
-      padding: edgePadding,
-    }),
-  );
+  // Add flip middleware only if enabled (to automatically change position when necessary)
+  if (enableFlip) {
+    middlewares.push(
+      flip({
+        // Specify explicit fallback placements to prevent infinite loops
+        // This prevents floating-ui from trying all possible positions rapidly
+        fallbackPlacements: ['top', 'bottom', 'right', 'left'],
+        fallbackAxisSideDirection: 'start',
+        // Use fallbackStrategy 'initialPlacement' to prefer staying close to the original position
+        fallbackStrategy: 'initialPlacement',
+        padding: edgePadding,
+      }),
+    );
+  }
 
   // Add shift to keep element in viewport
   middlewares.push(
     shift({
+      // Limit shift to prevent excessive movement that can trigger re-flips
+      limiter: {
+        fn: ({ placement, x, y }) => {
+          // Limit maximum shift to prevent position oscillation
+          return { placement, x, y };
+        },
+      },
       padding: edgePadding,
     }),
   );
@@ -139,6 +155,7 @@ export const getMiddlewareStack = ({
   arrowElement,
   customMiddlewares,
   edgePadding,
+  enableFlip,
   hideWhenDetached,
   isBodyAnchor,
   mainAxisOffset,
@@ -148,11 +165,12 @@ export const getMiddlewareStack = ({
   isBodyAnchor: boolean;
   edgePadding: number;
   mainAxisOffset: number;
-  placement?: Placement;
+  placement?: BodyDirection;
   offsetDistance?: [number, number];
   customMiddlewares?: Array<Middleware>;
   arrowElement?: HTMLElement | null;
   hideWhenDetached?: boolean;
+  enableFlip?: boolean;
 }): Middleware[] => {
   let middlewareStack: Middleware[];
 
@@ -162,12 +180,13 @@ export const getMiddlewareStack = ({
   } else {
     // Add positioning middleware based on anchor type
     if (isBodyAnchor) {
-      middlewareStack = createBodyAnchorMiddlewares(placement, edgePadding);
+      middlewareStack = createBodyAnchorMiddlewares(edgePadding, placement);
     } else {
       middlewareStack = createElementAnchorMiddlewares(
         mainAxisOffset,
-        offsetDistance,
         edgePadding,
+        offsetDistance,
+        enableFlip,
       );
     }
   }
@@ -192,7 +211,7 @@ export const calculateMainAxisOffset = ({
   hasArrow,
   offsetDistance,
 }: {
-  offsetDistance: [number, number] | undefined;
+  offsetDistance?: [number, number];
   hasArrow: boolean;
   arrowSize: number;
 }): number => {

packages/components/src/components/popover/hooks/positioning/positionStyles.ts

@@ -3,9 +3,8 @@
  */
 import type { Middleware, Strategy } from '@floating-ui/dom';
 
-import type { BodyDirection } from '../../utils/placement.utils';
-
 import { DEFAULT_PLACEMENT } from '../../types/animation';
+import type { BodyDirection } from '../../utils/placement.utils';
 
 /**
  * Generates CSS position styles based on positioning parameters

packages/components/src/components/popover/hooks/positioning/types.ts

@@ -1,6 +1,7 @@
-import type { Middleware, Placement, Strategy } from '@floating-ui/dom';
+import type { Middleware, Strategy } from '@floating-ui/dom';
 
 import type { ArrowStyles } from '../../types/popover';
+import type { BodyDirection } from '../../utils/placement.utils';
 
 /**
  * Options for positioning middlewares
@@ -12,19 +13,21 @@ import type { ArrowStyles } from '../../types/popover';
  * @property {[number, number]} [offsetDistance] - Optional offset distance of the popover from the anchor [main axis, cross axis] in pixels
  * @property {number} [edgePadding] - Optional padding for flip and shift middlewares to ensure popover stays within viewport bounds
  * @property {boolean} [hideWhenDetached] - Whether to hide the popover when the anchor element is not visible due to scrolling or being outside the viewport
+ * @property {boolean} [enableFlip] - Whether to enable automatic repositioning (flip) when there isn't enough space. Default: true
  */
 export interface PositioningMiddlewareOptions {
   offsetDistance?: [number, number];
   edgePadding?: number;
   hideWhenDetached?: boolean;
+  enableFlip?: boolean;
 }
 
 /**
  * Internal values used by the positioning system
  */
 export interface PositioningValues {
   anchorElement?: HTMLElement | null;
-  placement?: Placement;
+  placement?: BodyDirection;
   middlewareOptions: PositioningMiddlewareOptions;
   middlewares: Array<Middleware>;
   strategy: Strategy;

packages/components/src/components/popover/hooks/types/usePopoverInteractions.ts

@@ -12,5 +12,5 @@ interface IUsePopoverInteractionsResponse {
 }
 
 export type IUsePopoverInteractions = (
-  params: IUsePopoverInteractionsParams,
+  params: IUsePopoverInteractionsParams
 ) => IUsePopoverInteractionsResponse;

packages/components/src/components/popover/hooks/usePopoverPositioning.ts

@@ -1,3 +1,9 @@
+/**
+ * Specialized hook to handle everything related to popover positioning,
+ * including middlewares, position styles and arrows.
+ */
+import { type RefObject, useCallback, useEffect, useRef } from 'react';
+
 import {
   type Middleware,
   type MiddlewareData,
@@ -6,23 +12,17 @@ import {
   autoUpdate,
   computePosition as computePositionFloating,
 } from '@floating-ui/dom';
-/**
- * Specialized hook to handle everything related to popover positioning,
- * including middlewares, position styles and arrows.
- */
-import { type RefObject, useCallback, useEffect, useRef } from 'react';
 
 import type { BodyDirection } from '../utils/placement.utils';
-import type { PositioningValues } from './positioning/types';
-import type { IUsePopoverPositioning } from './types/usePopoverPositioning';
-
 import { positionArrow } from './positioning/arrowPositionStyles';
 import {
   calculateMainAxisOffset,
   getMiddlewareStack,
 } from './positioning/middlewareUtils';
 import { determinePositioningConfig } from './positioning/positionCalculation';
 import { applyPositionStyles } from './positioning/positionStyles';
+import type { PositioningValues } from './positioning/types';
+import type { IUsePopoverPositioning } from './types/usePopoverPositioning';
 
 /**
  * Hook that handles popover positioning and its related components
@@ -33,13 +33,17 @@ export const usePopoverPositioning: IUsePopoverPositioning = ({
   isVisible,
   middlewareOptions = {},
   middlewares = [],
-  placement,
+  placement: placementProp,
   ref,
   strategy,
 }) => {
+  // Normalize placement: 'top' for element anchors, 'center' for body anchor
+  const placement = placementProp ?? (anchorElement ? 'top' : 'center');
+
   // Default values for middleware options
   const {
     edgePadding = 0,
+    enableFlip,
     hideWhenDetached,
     offsetDistance,
   } = middlewareOptions;
@@ -181,6 +185,7 @@ export const usePopoverPositioning: IUsePopoverPositioning = ({
         computedPlacement,
         currentOffsetDistance,
         arrowSize,
+        arrowStyles?.padding,
       );
 
       // Invoke callback if provided
@@ -192,13 +197,13 @@ export const usePopoverPositioning: IUsePopoverPositioning = ({
   // Helper to prepare positioning data
   const preparePositioningData = useCallback(
     (
-      currentOffsetDistance: [number, number] | undefined,
       arrowSize: number,
       isBodyAnchor: boolean,
       currentEdgePadding: number,
-      currentPlacement: Placement | undefined,
       currentMiddlewares: Middleware[],
       currentMiddlewareOptions: { hideWhenDetached?: boolean },
+      currentPlacement?: BodyDirection,
+      currentOffsetDistance?: [number, number],
     ) => {
       const mainAxisOffset = calculateMainAxisOffset({
         arrowSize,
@@ -210,6 +215,7 @@ export const usePopoverPositioning: IUsePopoverPositioning = ({
         arrowElement,
         customMiddlewares: currentMiddlewares,
         edgePadding: currentEdgePadding,
+        enableFlip,
         hideWhenDetached: currentMiddlewareOptions?.hideWhenDetached,
         isBodyAnchor,
         mainAxisOffset,
@@ -227,18 +233,18 @@ export const usePopoverPositioning: IUsePopoverPositioning = ({
       currentRef: RefObject<HTMLElement | null>,
       middlewareData: MiddlewareData,
       isBodyAnchor: boolean,
-      currentPlacement: BodyDirection | undefined,
       x: number,
       y: number,
       currentStrategy: Strategy,
       currentEdgePadding: number,
       arrowElement: Element | null,
       computedPlacement: Placement,
-      currentOffsetDistance: [number, number] | undefined,
       arrowSize: number,
-      currentOnPositioned: (() => void) | undefined,
       customMiddlewares: Middleware[] = [],
       middlewareStack: Middleware[] = [],
+      currentPlacement?: BodyDirection,
+      currentOffsetDistance?: [number, number],
+      currentOnPositioned?: () => void,
     ) => {
       const shouldHide =
         middlewareData.hide?.referenceHidden || middlewareData.hide?.escaped;
@@ -247,6 +253,9 @@ export const usePopoverPositioning: IUsePopoverPositioning = ({
       if (currentRef.current) {
         currentRef.current.style.opacity = shouldHide ? '0' : '';
         currentRef.current.style.pointerEvents = shouldHide ? 'none' : '';
+        // Ensure visibility is restored even when shouldHide is true
+        // to remove the initial CSS visibility:hidden used to prevent scroll jumps
+        currentRef.current.style.visibility = shouldHide ? 'hidden' : 'visible';
       }
 
       // Apply positioning styles only if popover should be visible
@@ -305,13 +314,13 @@ export const usePopoverPositioning: IUsePopoverPositioning = ({
 
     // Prepare positioning data
     const { arrowElement, middlewareStack } = preparePositioningData(
-      currentOffsetDistance,
       arrowSize,
       isBodyAnchor,
       currentEdgePadding,
-      currentPlacement,
       currentMiddlewares,
       currentMiddlewareOptions || {},
+      currentPlacement,
+      currentOffsetDistance,
     );
 
     // Get positioning configuration
@@ -343,18 +352,18 @@ export const usePopoverPositioning: IUsePopoverPositioning = ({
       currentRef,
       middlewareData,
       isBodyAnchor,
-      actualPlacement,
       x,
       y,
       currentStrategy,
       currentEdgePadding,
       arrowElement,
       computedPlacement,
-      currentOffsetDistance,
       arrowSize,
-      currentOnPositioned,
       currentMiddlewares,
       middlewareStack,
+      actualPlacement,
+      currentOffsetDistance,
+      currentOnPositioned,
     );
   }, []);
 

packages/components/src/components/popover/index.ts

@@ -1,4 +1,4 @@
-export * from './animations/spring.animations';
-export { Popover } from './popover';
-export * from './positioning/middlewares';
-export type { PopoverStyleProps } from './types/popoverTheme';
+export { Popover } from "./popover";
+export * from "./positioning/middlewares";
+export { createSpringAnimation } from "./animations/spring.animations";
+export type { PopoverStyleProps } from "./types/popoverTheme";