From 42dbe90e52753f16880280bab5a2f24a93ba44a3 Mon Sep 17 00:00:00 2001
From: Kamil Emeleev <emeleev.kamil@gmail.com>
Date: Tue, 28 Jul 2026 19:39:56 +0300
Subject: [PATCH 1/4] fix(components): correct Tooltip and Popover arrow
 alignment

---
 .../src/components/Popover/Popover.test.tsx   |  96 ++++++-
 .../src/components/Popover/PopoverInner.tsx   |  25 +-
 .../src/components/Popover/types.ts           |   2 +-
 .../src/components/Tooltip/Tooltip.test.tsx   |  80 +++++-
 .../src/components/Tooltip/Tooltip.tsx        |  17 +-
 .../src/hooks/useOverlayArrowStyle/index.ts   |   1 +
 .../useOverlayArrowStyle.test.ts              | 253 ++++++++++++++++++
 .../useOverlayArrowStyle.ts                   | 164 ++++++++++++
 8 files changed, 631 insertions(+), 7 deletions(-)
 create mode 100644 packages/components/src/hooks/useOverlayArrowStyle/index.ts
 create mode 100644 packages/components/src/hooks/useOverlayArrowStyle/useOverlayArrowStyle.test.ts
 create mode 100644 packages/components/src/hooks/useOverlayArrowStyle/useOverlayArrowStyle.ts

diff --git a/packages/components/src/components/Popover/Popover.test.tsx b/packages/components/src/components/Popover/Popover.test.tsx
index 3da2c874e..cef3d9c7d 100644
--- a/packages/components/src/components/Popover/Popover.test.tsx
+++ b/packages/components/src/components/Popover/Popover.test.tsx
@@ -1,6 +1,6 @@
 import { createRef } from 'react';
 
-import { render, screen } from '@testing-library/react';
+import { render, screen, waitFor } from '@testing-library/react';
 import { userEvent } from '@testing-library/user-event';
 import { describe, expect, it, vi, beforeEach } from 'vitest';
 
@@ -64,6 +64,100 @@ describe('Popover', () => {
     expect(getRoot()).not.toHaveAttribute('data-arrow');
   });
 
+  it('should align the arrow for a compound placement', async () => {
+    const getBoundingClientRect = vi
+      .spyOn(HTMLElement.prototype, 'getBoundingClientRect')
+      .mockImplementation(function (this: HTMLElement) {
+        if (this.dataset.testid === 'root') {
+          return {
+            bottom: 64,
+            height: 64,
+            left: 0,
+            right: 200,
+            top: 0,
+            width: 200,
+            x: 0,
+            y: 0,
+          } as DOMRect;
+        }
+
+        if (this.tagName === 'BUTTON') {
+          return {
+            bottom: 32,
+            height: 32,
+            left: 0,
+            right: 100,
+            top: 0,
+            width: 100,
+            x: 0,
+            y: 0,
+          } as DOMRect;
+        }
+
+        return {
+          bottom: 0,
+          height: 0,
+          left: 0,
+          right: 0,
+          top: 0,
+          width: 0,
+          x: 0,
+          y: 0,
+        } as DOMRect;
+      });
+
+    const { rerender } = render(
+      <Popover
+        {...baseProps}
+        isOpen
+        placement="top start"
+        control={(props) => <Button {...props} />}
+      />
+    );
+
+    await waitFor(() => {
+      expect(getRoot().querySelector('[role="presentation"]')).toHaveStyle({
+        left: '20px',
+      });
+    });
+
+    rerender(
+      <Popover
+        {...baseProps}
+        isOpen
+        placement="top start"
+        arrowBoundaryOffset={24}
+        control={(props) => <Button {...props} />}
+      />
+    );
+
+    await waitFor(() => {
+      expect(getRoot().querySelector('[role="presentation"]')).toHaveStyle({
+        left: '24px',
+      });
+    });
+
+    getBoundingClientRect.mockRestore();
+  });
+
+  it('should keep arrow slot styles as the highest priority', async () => {
+    render(
+      <Popover
+        {...baseProps}
+        isOpen
+        placement="top start"
+        slotProps={{ arrow: { style: { left: 32 } } }}
+        control={(props) => <Button {...props} />}
+      />
+    );
+
+    await waitFor(() => {
+      expect(getRoot().querySelector('[role="presentation"]')).toHaveStyle({
+        left: '32px',
+      });
+    });
+  });
+
   it('should apply the focus trap', async () => {
     render(
       <>
diff --git a/packages/components/src/components/Popover/PopoverInner.tsx b/packages/components/src/components/Popover/PopoverInner.tsx
index 07437a691..f59f20c90 100644
--- a/packages/components/src/components/Popover/PopoverInner.tsx
+++ b/packages/components/src/components/Popover/PopoverInner.tsx
@@ -1,7 +1,13 @@
 import type { ComponentRef, CSSProperties, FC } from 'react';
 import { useRef } from 'react';
 
-import { clsx, mergeProps, useBoolean, useDOMRef } from '@koobiq/react-core';
+import {
+  clsx,
+  useLocale,
+  mergeProps,
+  useBoolean,
+  useDOMRef,
+} from '@koobiq/react-core';
 import {
   Overlay,
   useOverlayTrigger,
@@ -10,6 +16,7 @@ import {
 import { Transition } from 'react-transition-group';
 import type { TransitionProps } from 'react-transition-group/Transition';
 
+import { useOverlayArrowStyle } from '../../hooks/useOverlayArrowStyle';
 import { Dialog } from '../Dialog';
 
 import s from './Popover.module.css';
@@ -48,6 +55,8 @@ export const PopoverInner: FC<PopoverInnerProps> = (props) => {
   const domRef = useDOMRef<ComponentRef<'div'>>(popoverRef);
 
   const controlRef = useRef<HTMLButtonElement | null>(null);
+  const targetRef = anchorRef || controlRef;
+  const { direction } = useLocale();
 
   const openState = state.isOpen;
 
@@ -75,15 +84,25 @@ export const PopoverInner: FC<PopoverInnerProps> = (props) => {
       maxHeight: maxBlockSize,
       placement: placementProp,
       shouldCloseOnInteractOutside,
-      triggerRef: anchorRef || controlRef,
+      triggerRef: targetRef,
       isKeyboardDismissDisabled: disableExitOnEscapeKeyDown,
     },
     { ...state, isOpen: openState || opened }
   );
 
+  const arrowStyle = useOverlayArrowStyle({
+    direction,
+    placement: placementProp,
+    arrowBoundaryOffset,
+    arrowStyle: arrowPropsCommon.style,
+    isEnabled: showArrow,
+    overlayRef: domRef,
+    targetRef,
+  });
+
   const arrowProps = mergeProps(
     { className: s.arrow },
-    arrowPropsCommon,
+    { ...arrowPropsCommon, style: arrowStyle },
     slotProps?.arrow
   );
 
diff --git a/packages/components/src/components/Popover/types.ts b/packages/components/src/components/Popover/types.ts
index d1349801c..cb45bcd67 100644
--- a/packages/components/src/components/Popover/types.ts
+++ b/packages/components/src/components/Popover/types.ts
@@ -136,7 +136,7 @@ export type PopoverProps = {
   isNonModal?: boolean;
   /**
    * The minimum distance the arrow's edge should be from the edge of the overlay element.
-   * @default 0
+   * @default 20
    */
   arrowBoundaryOffset?: number;
   /**
diff --git a/packages/components/src/components/Tooltip/Tooltip.test.tsx b/packages/components/src/components/Tooltip/Tooltip.test.tsx
index bad58e811..f4d01075f 100644
--- a/packages/components/src/components/Tooltip/Tooltip.test.tsx
+++ b/packages/components/src/components/Tooltip/Tooltip.test.tsx
@@ -1,6 +1,6 @@
 import { createRef } from 'react';
 
-import { act, render, screen } from '@testing-library/react';
+import { act, render, screen, waitFor } from '@testing-library/react';
 import { userEvent } from '@testing-library/user-event';
 import { describe, expect, it, vi, beforeEach } from 'vitest';
 
@@ -69,6 +69,84 @@ describe('Tooltip', () => {
     expect(getRoot()).toHaveAttribute('data-arrow', 'true');
   });
 
+  it('should align the arrow for a compound placement', async () => {
+    const getBoundingClientRect = vi
+      .spyOn(HTMLElement.prototype, 'getBoundingClientRect')
+      .mockImplementation(function (this: HTMLElement) {
+        if (this.dataset.testid === 'root') {
+          return {
+            bottom: 64,
+            height: 64,
+            left: 0,
+            right: 200,
+            top: 0,
+            width: 200,
+            x: 0,
+            y: 0,
+          } as DOMRect;
+        }
+
+        if (this.tagName === 'BUTTON') {
+          return {
+            bottom: 32,
+            height: 32,
+            left: 0,
+            right: 100,
+            top: 0,
+            width: 100,
+            x: 0,
+            y: 0,
+          } as DOMRect;
+        }
+
+        return {
+          bottom: 0,
+          height: 0,
+          left: 0,
+          right: 0,
+          top: 0,
+          width: 0,
+          x: 0,
+          y: 0,
+        } as DOMRect;
+      });
+
+    const { rerender } = render(
+      <Tooltip
+        {...baseProps}
+        isOpen
+        hideArrow={false}
+        placement="top start"
+        control={(props) => <button {...props} />}
+      />
+    );
+
+    await waitFor(() => {
+      expect(getRoot().querySelector('[role="presentation"]')).toHaveStyle({
+        left: '16px',
+      });
+    });
+
+    rerender(
+      <Tooltip
+        {...baseProps}
+        isOpen
+        hideArrow={false}
+        placement="top start"
+        arrowBoundaryOffset={24}
+        control={(props) => <button {...props} />}
+      />
+    );
+
+    await waitFor(() => {
+      expect(getRoot().querySelector('[role="presentation"]')).toHaveStyle({
+        left: '24px',
+      });
+    });
+
+    getBoundingClientRect.mockRestore();
+  });
+
   it('should apply the focus trap', async () => {
     render(
       <>
diff --git a/packages/components/src/components/Tooltip/Tooltip.tsx b/packages/components/src/components/Tooltip/Tooltip.tsx
index d76e28973..a4de5b9d5 100644
--- a/packages/components/src/components/Tooltip/Tooltip.tsx
+++ b/packages/components/src/components/Tooltip/Tooltip.tsx
@@ -6,6 +6,7 @@ import { deprecate } from '@koobiq/logger';
 import {
   clsx,
   useDOMRef,
+  useLocale,
   mergeProps,
   useBoolean,
   useMultiRef,
@@ -20,6 +21,7 @@ import {
 } from '@koobiq/react-primitives';
 import { Transition } from 'react-transition-group';
 
+import { useOverlayArrowStyle } from '../../hooks/useOverlayArrowStyle';
 import { utilClasses } from '../../styles/utility';
 
 import s from './Tooltip.module.css';
@@ -83,6 +85,8 @@ export const Tooltip = forwardRef<TooltipRef, TooltipProps>((props, ref) => {
   const domRef = useDOMRef<ComponentRef<'div'>>(ref);
   const controlRef = useRef<FocusableElement>(null);
   const controlRefCallback = useMultiRef([controlRef]);
+  const targetRef = anchorRef || controlRef;
+  const { direction } = useLocale();
 
   const { triggerProps, tooltipProps: tooltipTriggerProps } = useTooltipTrigger(
     {
@@ -111,11 +115,21 @@ export const Tooltip = forwardRef<TooltipRef, TooltipProps>((props, ref) => {
     arrowBoundaryOffset,
     placement: placementProp,
     onClose: () => state.close(true),
-    targetRef: anchorRef || controlRef,
+    targetRef,
   });
 
   const { tooltipProps: tooltipCommonProps } = useTooltip(overlayProps, state);
 
+  const arrowStyle = useOverlayArrowStyle({
+    direction,
+    placement: placementProp,
+    arrowBoundaryOffset,
+    arrowStyle: arrowProps.style,
+    isEnabled: showArrow,
+    overlayRef: domRef,
+    targetRef,
+  });
+
   const tooltipProps = mergeProps(
     {
       className: clsx(
@@ -157,6 +171,7 @@ export const Tooltip = forwardRef<TooltipRef, TooltipProps>((props, ref) => {
               {showArrow && (
                 <div
                   {...arrowProps}
+                  style={arrowStyle}
                   className={s.arrow}
                   data-placement={placement}
                 />
diff --git a/packages/components/src/hooks/useOverlayArrowStyle/index.ts b/packages/components/src/hooks/useOverlayArrowStyle/index.ts
new file mode 100644
index 000000000..2a8c8ebfd
--- /dev/null
+++ b/packages/components/src/hooks/useOverlayArrowStyle/index.ts
@@ -0,0 +1 @@
+export { useOverlayArrowStyle } from './useOverlayArrowStyle';
diff --git a/packages/components/src/hooks/useOverlayArrowStyle/useOverlayArrowStyle.test.ts b/packages/components/src/hooks/useOverlayArrowStyle/useOverlayArrowStyle.test.ts
new file mode 100644
index 000000000..cc69f4dba
--- /dev/null
+++ b/packages/components/src/hooks/useOverlayArrowStyle/useOverlayArrowStyle.test.ts
@@ -0,0 +1,253 @@
+import type { CSSProperties } from 'react';
+
+import { renderHook, waitFor } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  getOverlayArrowStyle,
+  useOverlayArrowStyle,
+} from './useOverlayArrowStyle';
+
+const createRect = ({
+  height = 64,
+  left = 0,
+  top = 0,
+  width = 64,
+}: {
+  height?: number;
+  left?: number;
+  top?: number;
+  width?: number;
+} = {}) => ({
+  bottom: top + height,
+  left,
+  right: left + width,
+  top,
+});
+
+const overlayRect = createRect();
+const targetRect = createRect();
+
+describe('getOverlayArrowStyle', () => {
+  it.each([
+    ['top start', 'left', 16],
+    ['bottom start', 'left', 16],
+    ['top end', 'left', 'calc(100% - 16px)'],
+    ['bottom end', 'left', 'calc(100% - 16px)'],
+    ['start top', 'top', 16],
+    ['end top', 'top', 16],
+    ['start bottom', 'top', 'calc(100% - 16px)'],
+    ['end bottom', 'top', 'calc(100% - 16px)'],
+  ] as const)(
+    'should align the arrow for the "%s" placement',
+    (placement, property, value) => {
+      expect(
+        getOverlayArrowStyle({
+          placement,
+          direction: 'ltr',
+          arrowBoundaryOffset: 16,
+          overlayRect,
+          targetRect,
+        })
+      ).toMatchObject({ [property]: value });
+    }
+  );
+
+  it.each([
+    ['top start', 'bottom start'],
+    ['top end', 'bottom end'],
+    ['start top', 'end top'],
+    ['start bottom', 'end bottom'],
+  ] as const)(
+    'should preserve the arrow alignment when "%s" flips to "%s"',
+    (placement, flippedPlacement) => {
+      const options = {
+        direction: 'ltr' as const,
+        arrowBoundaryOffset: 16,
+        overlayRect,
+        targetRect,
+      };
+
+      expect(
+        getOverlayArrowStyle({ ...options, placement: flippedPlacement })
+      ).toEqual(getOverlayArrowStyle({ ...options, placement }));
+    }
+  );
+
+  it.each(['top', 'bottom', 'start', 'end'])(
+    'should preserve React Aria centering for the "%s" placement',
+    (placement) => {
+      expect(
+        getOverlayArrowStyle({
+          placement,
+          direction: 'ltr',
+          arrowBoundaryOffset: 16,
+        })
+      ).toBeUndefined();
+    }
+  );
+
+  it.each([
+    ['top start', 'calc(100% - 16px)'],
+    ['bottom start', 'calc(100% - 16px)'],
+    ['top end', 16],
+    ['bottom end', 16],
+  ] as const)(
+    'should use the "%s" logical alignment in RTL',
+    (placement, left) => {
+      expect(
+        getOverlayArrowStyle({
+          placement,
+          direction: 'rtl',
+          arrowBoundaryOffset: 16,
+          overlayRect,
+          targetRect,
+        })
+      ).toMatchObject({ left });
+    }
+  );
+
+  it('should apply a custom arrow boundary offset', () => {
+    expect(
+      getOverlayArrowStyle({
+        direction: 'ltr',
+        placement: 'top start',
+        arrowBoundaryOffset: 24,
+        overlayRect,
+        targetRect,
+      })
+    ).toMatchObject({ left: 24 });
+  });
+
+  it.each([
+    [
+      'top start',
+      createRect({ left: 100 }),
+      createRect({ left: 0, width: 32 }),
+    ],
+    ['top end', createRect({ left: 0 }), createRect({ left: 100, width: 32 })],
+    ['start top', createRect({ top: 100 }), createRect({ height: 32, top: 0 })],
+    [
+      'start bottom',
+      createRect({ top: 0 }),
+      createRect({ height: 32, top: 100 }),
+    ],
+  ] as const)(
+    'should preserve React Aria positioning when the "%s" arrow would miss the target',
+    (placement, shiftedOverlayRect, shiftedTargetRect) => {
+      expect(
+        getOverlayArrowStyle({
+          placement,
+          direction: 'ltr',
+          arrowBoundaryOffset: 16,
+          overlayRect: shiftedOverlayRect,
+          targetRect: shiftedTargetRect,
+        })
+      ).toBeUndefined();
+    }
+  );
+
+  it.each([-1, 65])(
+    'should not apply an offset of %spx outside the overlay',
+    (arrowBoundaryOffset) => {
+      expect(
+        getOverlayArrowStyle({
+          direction: 'ltr',
+          placement: 'top start',
+          arrowBoundaryOffset,
+          overlayRect,
+          targetRect: createRect({ left: -10, width: 84 }),
+        })
+      ).toBeUndefined();
+    }
+  );
+
+  it('should use the fixed offset when the arrow still points at the target after a shift', () => {
+    expect(
+      getOverlayArrowStyle({
+        direction: 'ltr',
+        placement: 'top start',
+        arrowBoundaryOffset: 16,
+        overlayRect: createRect({ left: 12 }),
+        targetRect: createRect({ width: 40 }),
+      })
+    ).toMatchObject({ left: 16 });
+  });
+});
+
+const rect = {
+  bottom: 64,
+  left: 0,
+  right: 64,
+  top: 0,
+} as DOMRect;
+
+const createRef = () => ({
+  current: {
+    getBoundingClientRect: vi.fn(() => rect),
+  } as unknown as Element,
+});
+
+describe('useOverlayArrowStyle', () => {
+  it.each([
+    { isEnabled: false, placement: 'top start' },
+    { isEnabled: true, placement: 'top' },
+  ])(
+    'should not measure elements for $placement when isEnabled is $isEnabled',
+    ({ isEnabled, placement }) => {
+      const overlayRef = createRef();
+      const targetRef = createRef();
+      const arrowStyle: CSSProperties = { left: 32 };
+
+      const { result } = renderHook(() =>
+        useOverlayArrowStyle({
+          isEnabled,
+          placement,
+          arrowStyle,
+          overlayRef,
+          targetRef,
+          direction: 'ltr',
+          arrowBoundaryOffset: 16,
+        })
+      );
+
+      expect(overlayRef.current.getBoundingClientRect).not.toHaveBeenCalled();
+      expect(targetRef.current.getBoundingClientRect).not.toHaveBeenCalled();
+      expect(result.current).toBe(arrowStyle);
+    }
+  );
+
+  it('should merge only the positional override with the latest React Aria style', async () => {
+    const overlayRef = createRef();
+    const targetRef = createRef();
+    const initialArrowStyle: CSSProperties = { left: 32 };
+
+    const { rerender, result } = renderHook(
+      ({ arrowStyle }) =>
+        useOverlayArrowStyle({
+          arrowStyle,
+          overlayRef,
+          targetRef,
+          isEnabled: true,
+          direction: 'ltr',
+          placement: 'top start',
+          arrowBoundaryOffset: 16,
+        }),
+      { initialProps: { arrowStyle: initialArrowStyle } }
+    );
+
+    await waitFor(() => expect(result.current).toEqual({ left: 16 }));
+
+    const nextArrowStyle: CSSProperties = {
+      left: 40,
+      position: 'absolute',
+    };
+
+    rerender({ arrowStyle: nextArrowStyle });
+
+    expect(result.current).toEqual({
+      left: 16,
+      position: 'absolute',
+    });
+  });
+});
diff --git a/packages/components/src/hooks/useOverlayArrowStyle/useOverlayArrowStyle.ts b/packages/components/src/hooks/useOverlayArrowStyle/useOverlayArrowStyle.ts
new file mode 100644
index 000000000..dcb3aa63f
--- /dev/null
+++ b/packages/components/src/hooks/useOverlayArrowStyle/useOverlayArrowStyle.ts
@@ -0,0 +1,164 @@
+import type { CSSProperties } from 'react';
+import { useLayoutEffect, useState } from 'react';
+
+type Direction = 'ltr' | 'rtl';
+
+type Rect = Pick<DOMRect, 'bottom' | 'left' | 'right' | 'top'>;
+
+type GetOverlayArrowStyleOptions = {
+  arrowBoundaryOffset: number;
+  direction: Direction;
+  overlayRect?: Rect;
+  placement: string;
+  targetRect?: Rect;
+};
+
+type CrossAxisEdge = 'bottom' | 'left' | 'right' | 'top';
+
+const getCrossAxisEdge = (
+  placement: string,
+  direction: Direction
+): CrossAxisEdge | undefined => {
+  const [side, alignment] = placement.split(' ');
+
+  if (
+    (side === 'top' || side === 'bottom') &&
+    (alignment === 'start' || alignment === 'end')
+  ) {
+    const isStart = alignment === 'start';
+    const isLeft = direction === 'ltr' ? isStart : !isStart;
+
+    return isLeft ? 'left' : 'right';
+  }
+
+  if (
+    (side === 'start' || side === 'end') &&
+    (alignment === 'top' || alignment === 'bottom')
+  ) {
+    return alignment;
+  }
+
+  return undefined;
+};
+
+const isArrowPointingAtTarget = (
+  edge: CrossAxisEdge,
+  arrowBoundaryOffset: number,
+  overlayRect: Rect,
+  targetRect: Rect
+) => {
+  const isHorizontal = edge === 'left' || edge === 'right';
+
+  const arrowCenter = isHorizontal
+    ? edge === 'left'
+      ? overlayRect.left + arrowBoundaryOffset
+      : overlayRect.right - arrowBoundaryOffset
+    : edge === 'top'
+      ? overlayRect.top + arrowBoundaryOffset
+      : overlayRect.bottom - arrowBoundaryOffset;
+
+  const overlayStart = isHorizontal ? overlayRect.left : overlayRect.top;
+  const overlayEnd = isHorizontal ? overlayRect.right : overlayRect.bottom;
+  const targetStart = isHorizontal ? targetRect.left : targetRect.top;
+  const targetEnd = isHorizontal ? targetRect.right : targetRect.bottom;
+
+  return (
+    arrowCenter >= overlayStart &&
+    arrowCenter <= overlayEnd &&
+    arrowCenter >= targetStart &&
+    arrowCenter <= targetEnd
+  );
+};
+
+const hasOverlayArrowAlignment = (placement: string) =>
+  getCrossAxisEdge(placement, 'ltr') !== undefined;
+
+export const getOverlayArrowStyle = ({
+  arrowBoundaryOffset,
+  direction,
+  overlayRect,
+  placement,
+  targetRect,
+}: GetOverlayArrowStyleOptions): CSSProperties | undefined => {
+  const edge = getCrossAxisEdge(placement, direction);
+
+  if (
+    !edge ||
+    !overlayRect ||
+    !targetRect ||
+    !isArrowPointingAtTarget(edge, arrowBoundaryOffset, overlayRect, targetRect)
+  ) {
+    return undefined;
+  }
+
+  if (edge === 'left' || edge === 'right') {
+    return {
+      left:
+        edge === 'left'
+          ? arrowBoundaryOffset
+          : `calc(100% - ${arrowBoundaryOffset}px)`,
+    };
+  }
+
+  return {
+    top:
+      edge === 'top'
+        ? arrowBoundaryOffset
+        : `calc(100% - ${arrowBoundaryOffset}px)`,
+  };
+};
+
+type ElementRef = {
+  readonly current: Element | null;
+};
+
+type UseOverlayArrowStyleOptions = {
+  arrowBoundaryOffset: number;
+  arrowStyle?: CSSProperties;
+  direction: Direction;
+  isEnabled: boolean;
+  overlayRef: ElementRef;
+  placement: string;
+  targetRef: ElementRef;
+};
+
+const isSameArrowOverride = (current?: CSSProperties, next?: CSSProperties) =>
+  current?.left === next?.left && current?.top === next?.top;
+
+export const useOverlayArrowStyle = ({
+  arrowBoundaryOffset,
+  arrowStyle,
+  direction,
+  isEnabled,
+  overlayRef,
+  placement,
+  targetRef,
+}: UseOverlayArrowStyleOptions): CSSProperties | undefined => {
+  const [overrideStyle, setOverrideStyle] = useState<CSSProperties>();
+
+  useLayoutEffect(() => {
+    if (!isEnabled || !hasOverlayArrowAlignment(placement)) {
+      setOverrideStyle((currentStyle) =>
+        currentStyle === undefined ? currentStyle : undefined
+      );
+
+      return;
+    }
+
+    const nextOverride = getOverlayArrowStyle({
+      direction,
+      placement,
+      arrowBoundaryOffset,
+      overlayRect: overlayRef.current?.getBoundingClientRect(),
+      targetRect: targetRef.current?.getBoundingClientRect(),
+    });
+
+    setOverrideStyle((currentStyle) =>
+      isSameArrowOverride(currentStyle, nextOverride)
+        ? currentStyle
+        : nextOverride
+    );
+  });
+
+  return overrideStyle ? { ...arrowStyle, ...overrideStyle } : arrowStyle;
+};

From 467db07f7a9a5f3e710b615e494caec7967e4cf1 Mon Sep 17 00:00:00 2001
From: Kamil Emeleev <emeleev.kamil@gmail.com>
Date: Wed, 29 Jul 2026 12:49:24 +0300
Subject: [PATCH 2/4] chore(useOverlayArrowStyle): prevent useLayoutEffect
 during SSR in overlay arrow positioning

---
 .../useOverlayArrowStyle.ts                   | 20 ++++++++++++++++---
 1 file changed, 17 insertions(+), 3 deletions(-)

diff --git a/packages/components/src/hooks/useOverlayArrowStyle/useOverlayArrowStyle.ts b/packages/components/src/hooks/useOverlayArrowStyle/useOverlayArrowStyle.ts
index dcb3aa63f..335209c3b 100644
--- a/packages/components/src/hooks/useOverlayArrowStyle/useOverlayArrowStyle.ts
+++ b/packages/components/src/hooks/useOverlayArrowStyle/useOverlayArrowStyle.ts
@@ -1,5 +1,7 @@
 import type { CSSProperties } from 'react';
-import { useLayoutEffect, useState } from 'react';
+import { useState } from 'react';
+
+import { useIsomorphicEffect } from '@koobiq/react-core';
 
 type Direction = 'ltr' | 'rtl';
 
@@ -136,7 +138,10 @@ export const useOverlayArrowStyle = ({
 }: UseOverlayArrowStyleOptions): CSSProperties | undefined => {
   const [overrideStyle, setOverrideStyle] = useState<CSSProperties>();
 
-  useLayoutEffect(() => {
+  // React Aria recalculates the arrow offset every time it repositions the
+  // overlay, so its value is the signal to measure the elements again. The
+  // `arrowStyle` object is recreated on every render and can't be a dependency.
+  useIsomorphicEffect(() => {
     if (!isEnabled || !hasOverlayArrowAlignment(placement)) {
       setOverrideStyle((currentStyle) =>
         currentStyle === undefined ? currentStyle : undefined
@@ -158,7 +163,16 @@ export const useOverlayArrowStyle = ({
         ? currentStyle
         : nextOverride
     );
-  });
+  }, [
+    isEnabled,
+    placement,
+    direction,
+    arrowBoundaryOffset,
+    arrowStyle?.left,
+    arrowStyle?.top,
+    overlayRef,
+    targetRef,
+  ]);
 
   return overrideStyle ? { ...arrowStyle, ...overrideStyle } : arrowStyle;
 };

From d63443ba4e6e6dbd33da697b742307c1209983c1 Mon Sep 17 00:00:00 2001
From: Kamil Emeleev <emeleev.kamil@gmail.com>
Date: Wed, 5 Aug 2026 17:06:51 +0300
Subject: [PATCH 3/4] chore: approve api

---
 tools/public_api_guard/components/Tooltip.api.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tools/public_api_guard/components/Tooltip.api.md b/tools/public_api_guard/components/Tooltip.api.md
index 8ff906864..51d261bb4 100644
--- a/tools/public_api_guard/components/Tooltip.api.md
+++ b/tools/public_api_guard/components/Tooltip.api.md
@@ -19,7 +19,7 @@ import { TooltipTriggerProps } from 'react-aria';
 import type { TooltipTriggerProps as TooltipTriggerProps_2 } from '@koobiq/react-primitives';
 
 // @public
-export const Tooltip: ForwardRefExoticComponent<Omit<TooltipTriggerProps, "children" | "style" | "className" | "id" | "placement" | `data-${string}` | "variant" | "offset" | "control" | "portalContainer" | "anchorRef" | "hideArrow" | "arrowBoundaryOffset" | "crossOffset" | "delay" | "closeDelay" | keyof {
+export const Tooltip: ForwardRefExoticComponent<Omit<TooltipTriggerProps, "children" | "style" | "className" | "id" | "placement" | `data-${string}` | "variant" | "offset" | "control" | "portalContainer" | "arrowBoundaryOffset" | "anchorRef" | "hideArrow" | "crossOffset" | "delay" | "closeDelay" | keyof {
 open?: boolean;
 disabled?: boolean;
 }> & {

From 832678fa57c81226f252de3710e591d4e17424c1 Mon Sep 17 00:00:00 2001
From: Kamil Emeleev <emeleev.kamil@gmail.com>
Date: Thu, 6 Aug 2026 13:32:27 +0300
Subject: [PATCH 4/4] test(components): restore Tooltip and Popover spies after
 each test

---
 .../src/components/Popover/Popover.test.tsx      | 16 +++++++++-------
 .../src/components/Tooltip/Tooltip.test.tsx      | 16 +++++++++-------
 2 files changed, 18 insertions(+), 14 deletions(-)

diff --git a/packages/components/src/components/Popover/Popover.test.tsx b/packages/components/src/components/Popover/Popover.test.tsx
index cef3d9c7d..c0650323a 100644
--- a/packages/components/src/components/Popover/Popover.test.tsx
+++ b/packages/components/src/components/Popover/Popover.test.tsx
@@ -2,7 +2,7 @@ import { createRef } from 'react';
 
 import { render, screen, waitFor } from '@testing-library/react';
 import { userEvent } from '@testing-library/user-event';
-import { describe, expect, it, vi, beforeEach } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { Button } from '../Button';
 
@@ -13,6 +13,10 @@ describe('Popover', () => {
     vi.clearAllMocks();
   });
 
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
   const onOpenChange = vi.fn();
 
   const baseProps = { 'data-testid': 'root', onOpenChange };
@@ -65,9 +69,8 @@ describe('Popover', () => {
   });
 
   it('should align the arrow for a compound placement', async () => {
-    const getBoundingClientRect = vi
-      .spyOn(HTMLElement.prototype, 'getBoundingClientRect')
-      .mockImplementation(function (this: HTMLElement) {
+    vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(
+      function (this: HTMLElement) {
         if (this.dataset.testid === 'root') {
           return {
             bottom: 64,
@@ -104,7 +107,8 @@ describe('Popover', () => {
           x: 0,
           y: 0,
         } as DOMRect;
-      });
+      }
+    );
 
     const { rerender } = render(
       <Popover
@@ -136,8 +140,6 @@ describe('Popover', () => {
         left: '24px',
       });
     });
-
-    getBoundingClientRect.mockRestore();
   });
 
   it('should keep arrow slot styles as the highest priority', async () => {
diff --git a/packages/components/src/components/Tooltip/Tooltip.test.tsx b/packages/components/src/components/Tooltip/Tooltip.test.tsx
index f4d01075f..daa8da71d 100644
--- a/packages/components/src/components/Tooltip/Tooltip.test.tsx
+++ b/packages/components/src/components/Tooltip/Tooltip.test.tsx
@@ -2,7 +2,7 @@ import { createRef } from 'react';
 
 import { act, render, screen, waitFor } from '@testing-library/react';
 import { userEvent } from '@testing-library/user-event';
-import { describe, expect, it, vi, beforeEach } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { IconButton } from '../IconButton';
 
@@ -14,6 +14,10 @@ describe('Tooltip', () => {
     vi.clearAllMocks();
   });
 
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
   const onOpenChange = vi.fn();
 
   const baseProps = { 'data-testid': 'root', onOpenChange };
@@ -70,9 +74,8 @@ describe('Tooltip', () => {
   });
 
   it('should align the arrow for a compound placement', async () => {
-    const getBoundingClientRect = vi
-      .spyOn(HTMLElement.prototype, 'getBoundingClientRect')
-      .mockImplementation(function (this: HTMLElement) {
+    vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(
+      function (this: HTMLElement) {
         if (this.dataset.testid === 'root') {
           return {
             bottom: 64,
@@ -109,7 +112,8 @@ describe('Tooltip', () => {
           x: 0,
           y: 0,
         } as DOMRect;
-      });
+      }
+    );
 
     const { rerender } = render(
       <Tooltip
@@ -143,8 +147,6 @@ describe('Tooltip', () => {
         left: '24px',
       });
     });
-
-    getBoundingClientRect.mockRestore();
   });
 
   it('should apply the focus trap', async () => {