@redocly/theme 0.64.0 → 0.65.0-next.0

package/lib/components/Tooltip/AnchorTooltip.js

@@ -38,11 +38,18 @@ const react_1 = __importStar(require("react"));
 const styled_components_1 = __importStar(require("styled-components"));
 const hooks_1 = require("../../core/hooks");
 const Portal_1 = require("../../components/Portal/Portal");
-function TooltipComponent({ children, isOpen, tip, withArrow = true, placement = 'top', className = 'default', width, dataTestId, disabled = false, arrowPosition = 'center', onClick, }) {
+function TooltipComponent({ children, isOpen, tip, withArrow = true, placement = 'top', fallbackPlacements, className = 'default', width, dataTestId, disabled = false, arrowPosition = 'center', onClick, }) {
     const tooltipWrapperRef = (0, react_1.useRef)(null);
     const tooltipBodyRef = (0, react_1.useRef)(null);
     const { isOpened, handleOpen, handleClose } = (0, hooks_1.useControl)(isOpen);
     const anchorName = `--tooltip${(0, react_1.useId)().replace(/:/g, '')}`;
+    const { activePlacement, activeArrowPosition } = (0, hooks_1.useTooltipFallbackPlacement)({
+        isOpened,
+        placement,
+        arrowPosition,
+        fallbackPlacements,
+        tooltipBodyRef,
+    });
     (0, hooks_1.useOutsideClick)(isOpened ? [tooltipWrapperRef, tooltipBodyRef] : tooltipWrapperRef, handleClose);
     const isControlled = isOpen !== undefined;
     (0, react_1.useEffect)(() => {
@@ -70,7 +77,9 @@ function TooltipComponent({ children, isOpen, tip, withArrow = true, placement =
     return (react_1.default.createElement(TooltipWrapper, Object.assign({ ref: tooltipWrapperRef }, controllers, { className: `tooltip-${className}`, "data-component-name": "Tooltip/Tooltip", anchorName: anchorName }),
         children,
         isOpened && !disabled && (react_1.default.createElement(Portal_1.Portal, null,
-            react_1.default.createElement(TooltipBody, { ref: tooltipBodyRef, "data-testid": dataTestId || (typeof tip === 'string' ? tip : ''), placement: placement, width: width, withArrow: withArrow, arrowPosition: arrowPosition, anchorName: anchorName }, tip)))));
+            react_1.default.createElement(TooltipBody, { ref: tooltipBodyRef, "data-testid": dataTestId || (typeof tip === 'string' ? tip : ''), placement: activePlacement, width: width, withArrow: withArrow, arrowPosition: activeArrowPosition === 'left' || activeArrowPosition === 'right'
+                    ? activeArrowPosition
+                    : 'center', anchorName: anchorName }, tip)))));
 }
 exports.Tooltip = (0, react_1.memo)(TooltipComponent);
 const PLACEMENTS = {

package/lib/components/Tooltip/JsTooltip.js

@@ -38,56 +38,37 @@ const react_1 = __importStar(require("react"));
 const styled_components_1 = __importStar(require("styled-components"));
 const hooks_1 = require("../../core/hooks");
 const Portal_1 = require("../../components/Portal/Portal");
-function TooltipComponent({ children, isOpen, tip, withArrow = true, placement = 'top', className = 'default', width, dataTestId, disabled = false, arrowPosition = 'center', onClick, }) {
-    const ref = (0, react_1.useRef)(null);
+const utils_1 = require("../../core/utils");
+function TooltipComponent({ children, isOpen, tip, withArrow = true, placement = 'top', fallbackPlacements, className = 'default', width, dataTestId, disabled = false, arrowPosition = 'center', onClick, }) {
+    const wrapperRef = (0, react_1.useRef)(null);
+    const tooltipBodyRef = (0, react_1.useRef)(null);
     const { isOpened, handleOpen, handleClose } = (0, hooks_1.useControl)(isOpen);
     const [tooltipPosition, setTooltipPosition] = (0, react_1.useState)({ top: 0, left: 0 });
-    (0, hooks_1.useOutsideClick)(ref, handleClose);
+    const [activePlacement, setActivePlacement] = (0, react_1.useState)(placement);
+    const activeArrowPosition = activePlacement === placement ? arrowPosition : 'center';
+    (0, hooks_1.useOutsideClick)(wrapperRef, handleClose);
     const isControlled = isOpen !== undefined;
     const updateTooltipPosition = (0, react_1.useCallback)(() => {
-        if (isOpened && ref.current) {
-            const rect = ref.current.getBoundingClientRect();
-            let top = 0;
-            let left = 0;
-            switch (placement) {
-                case 'top':
-                    top = rect.top;
-                    if (arrowPosition === 'left') {
-                        left = rect.left - 24;
-                    }
-                    else if (arrowPosition === 'right') {
-                        left = rect.right + 24;
-                    }
-                    else {
-                        left = rect.left + rect.width / 2;
-                    }
-                    break;
-                case 'bottom':
-                    top = rect.bottom;
-                    if (arrowPosition === 'left') {
-                        left = rect.left - 24;
-                    }
-                    else if (arrowPosition === 'right') {
-                        left = rect.right + 24;
-                    }
-                    else {
-                        left = rect.left + rect.width / 2;
-                    }
-                    break;
-                case 'left':
-                    top = rect.top + rect.height / 2;
-                    left = rect.left;
-                    break;
-                case 'right':
-                    top = rect.top + rect.height / 2;
-                    left = rect.right;
-                    break;
-            }
-            setTooltipPosition({ top, left });
-        }
-    }, [isOpened, placement, arrowPosition]);
+        var _a, _b, _c, _d;
+        if (!isOpened || !wrapperRef.current)
+            return;
+        const triggerRect = wrapperRef.current.getBoundingClientRect();
+        const tooltipWidth = (_b = (_a = tooltipBodyRef.current) === null || _a === void 0 ? void 0 : _a.offsetWidth) !== null && _b !== void 0 ? _b : 0;
+        const tooltipHeight = (_d = (_c = tooltipBodyRef.current) === null || _c === void 0 ? void 0 : _c.offsetHeight) !== null && _d !== void 0 ? _d : 0;
+        const resolved = (0, utils_1.resolvePlacement)({
+            triggerRect,
+            tooltipWidth,
+            tooltipHeight,
+            placement,
+            arrowPosition,
+            fallbackPlacements,
+        });
+        const resolvedArrow = resolved === placement ? arrowPosition : 'center';
+        setTooltipPosition((0, utils_1.calcAnchorPoint)(triggerRect, resolved, resolvedArrow));
+        setActivePlacement(resolved);
+    }, [isOpened, placement, arrowPosition, fallbackPlacements]);
     (0, react_1.useLayoutEffect)(() => {
-        if (isOpened && ref.current) {
+        if (isOpened && wrapperRef.current) {
             updateTooltipPosition();
             const handleScroll = () => updateTooltipPosition();
             const handleResize = () => updateTooltipPosition();
@@ -118,10 +99,10 @@ function TooltipComponent({ children, isOpen, tip, withArrow = true, placement =
         onFocus: handleOpen,
         onBlur: handleClose,
     };
-    return (react_1.default.createElement(TooltipWrapper, Object.assign({ ref: ref }, controllers, { className: `tooltip-${className}`, "data-component-name": "Tooltip/Tooltip" }),
+    return (react_1.default.createElement(TooltipWrapper, Object.assign({ ref: wrapperRef }, controllers, { className: `tooltip-${className}`, "data-component-name": "Tooltip/Tooltip" }),
         children,
         isOpened && !disabled && (react_1.default.createElement(Portal_1.Portal, null,
-            react_1.default.createElement(TooltipBody, { "data-testid": dataTestId || (typeof tip === 'string' ? tip : ''), placement: placement, width: width, withArrow: withArrow, arrowPosition: arrowPosition, style: {
+            react_1.default.createElement(TooltipBody, { ref: tooltipBodyRef, "data-testid": dataTestId || (typeof tip === 'string' ? tip : ''), placement: activePlacement, width: width, withArrow: withArrow, arrowPosition: activeArrowPosition, style: {
                     position: 'fixed',
                     top: tooltipPosition.top,
                     left: tooltipPosition.left,

package/lib/components/Tooltip/Tooltip.d.ts

@@ -1,3 +1,3 @@
 import React from 'react';
-import { TooltipProps } from '../../core/types';
+import type { TooltipProps } from '../../core/types';
 export declare const Tooltip: React.NamedExoticComponent<TooltipProps>;

package/lib/components/Tooltip/Tooltip.js

@@ -38,13 +38,16 @@ const react_1 = __importStar(require("react"));
 const AnchorTooltip_1 = require("../../components/Tooltip/AnchorTooltip");
 const JsTooltip_1 = require("../../components/Tooltip/JsTooltip");
 const hooks_1 = require("../../core/hooks");
+const utils_1 = require("../../core/utils");
 function TooltipComponent(props) {
+    var _a, _b;
     const { useAnchorPositioning } = (0, hooks_1.useThemeHooks)();
     const { isSupported } = useAnchorPositioning();
+    const fallbackPlacements = (_a = props.fallbackPlacements) !== null && _a !== void 0 ? _a : (0, utils_1.getDefaultFallbackPlacements)((_b = props.placement) !== null && _b !== void 0 ? _b : 'top');
     if (isSupported) {
-        return react_1.default.createElement(AnchorTooltip_1.Tooltip, Object.assign({}, props, { arrowPosition: prepareArrowPosition(props.arrowPosition) }));
+        return (react_1.default.createElement(AnchorTooltip_1.Tooltip, Object.assign({}, props, { fallbackPlacements: fallbackPlacements, arrowPosition: prepareArrowPosition(props.arrowPosition) })));
     }
-    return react_1.default.createElement(JsTooltip_1.Tooltip, Object.assign({}, props));
+    return react_1.default.createElement(JsTooltip_1.Tooltip, Object.assign({}, props, { fallbackPlacements: fallbackPlacements }));
 }
 exports.Tooltip = (0, react_1.memo)(TooltipComponent);
 const prepareArrowPosition = (arrowPosition) => {

package/lib/core/hooks/index.d.ts

@@ -54,3 +54,4 @@ export * from './use-is-truncated';
 export * from './use-toast';
 export * from './use-toast-logic';
 export * from './use-banner-telemetry';
+export * from './use-tooltip-fallback-placement';

package/lib/core/hooks/index.js

@@ -70,4 +70,5 @@ __exportStar(require("./use-is-truncated"), exports);
 __exportStar(require("./use-toast"), exports);
 __exportStar(require("./use-toast-logic"), exports);
 __exportStar(require("./use-banner-telemetry"), exports);
+__exportStar(require("./use-tooltip-fallback-placement"), exports);
 //# sourceMappingURL=index.js.map

package/lib/core/hooks/use-tooltip-fallback-placement.d.ts

@@ -0,0 +1,15 @@
+import type { RefObject } from 'react';
+import type { TooltipPlacement, TooltipProps } from '../../core/types';
+type TooltipFallbackPlacementParams = {
+    isOpened: boolean;
+    placement: TooltipPlacement;
+    arrowPosition: TooltipProps['arrowPosition'];
+    fallbackPlacements: TooltipPlacement[] | undefined;
+    tooltipBodyRef: RefObject<HTMLElement | null>;
+};
+type TooltipFallbackPlacementResult = {
+    activePlacement: TooltipPlacement;
+    activeArrowPosition: TooltipProps['arrowPosition'];
+};
+export declare function useTooltipFallbackPlacement({ isOpened, placement, arrowPosition, fallbackPlacements, tooltipBodyRef, }: TooltipFallbackPlacementParams): TooltipFallbackPlacementResult;
+export {};

package/lib/core/hooks/use-tooltip-fallback-placement.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useTooltipFallbackPlacement = useTooltipFallbackPlacement;
+const react_1 = require("react");
+function useTooltipFallbackPlacement({ isOpened, placement, arrowPosition, fallbackPlacements, tooltipBodyRef, }) {
+    const [activePlacement, setActivePlacement] = (0, react_1.useState)(placement);
+    const wasOpenRef = (0, react_1.useRef)(false);
+    const candidateIndexRef = (0, react_1.useRef)(0);
+    (0, react_1.useLayoutEffect)(() => {
+        if (!isOpened) {
+            wasOpenRef.current = false;
+            candidateIndexRef.current = 0;
+            return;
+        }
+        if (!wasOpenRef.current) {
+            wasOpenRef.current = true;
+            candidateIndexRef.current = 0;
+            if (activePlacement !== placement) {
+                setActivePlacement(placement);
+                return;
+            }
+        }
+        if (!tooltipBodyRef.current || !(fallbackPlacements === null || fallbackPlacements === void 0 ? void 0 : fallbackPlacements.length))
+            return;
+        const candidates = [placement, ...fallbackPlacements];
+        if (candidateIndexRef.current >= candidates.length)
+            return;
+        const rect = tooltipBodyRef.current.getBoundingClientRect();
+        const overflows = rect.left < 0 ||
+            rect.top < 0 ||
+            rect.right > window.innerWidth ||
+            rect.bottom > window.innerHeight;
+        if (!overflows)
+            return;
+        candidateIndexRef.current++;
+        if (candidateIndexRef.current < candidates.length) {
+            setActivePlacement(candidates[candidateIndexRef.current]);
+        }
+        else if (activePlacement !== placement) {
+            setActivePlacement(placement);
+        }
+    }, [isOpened, activePlacement, placement, fallbackPlacements, tooltipBodyRef]);
+    const activeArrowPosition = activePlacement === placement ? arrowPosition : 'center';
+    return { activePlacement, activeArrowPosition };
+}
+//# sourceMappingURL=use-tooltip-fallback-placement.js.map

package/lib/core/styles/global.js

@@ -1232,6 +1232,7 @@ const replay = (0, styled_components_1.css) `
   --replay-runtime-expression-color: rgba(54, 90, 249, 1); // @presenter Color
   --replay-runtime-expression-bg-color: rgba(54, 90, 249, 0.08); // @presenter Color
   --replay-operators-color: rgba(193, 142, 31, 1); // @presenter Color
+  --replay-claude-icon-color: rgba(217, 119, 87, 1); // @presenter Color
 
   --replay-ai-gradient-soft: linear-gradient(62.6deg, rgba(113, 94, 254, 0.16) 0%, rgba(255, 92, 220, 0.16) 100%);
   --replay-ai-gradient-disabled: linear-gradient(62.6deg, rgba(113, 94, 254, 0.6) 0%, rgba(255, 92, 220, 0.6) 100%);

package/lib/core/types/tooltip.d.ts

@@ -1,10 +1,12 @@
 import type { ReactNode } from 'react';
+export type TooltipPlacement = 'top' | 'bottom' | 'left' | 'right';
 export type TooltipProps = {
     children?: ReactNode;
     tip: string | ReactNode;
     isOpen?: boolean;
     withArrow?: boolean;
-    placement?: 'top' | 'bottom' | 'left' | 'right';
+    placement?: TooltipPlacement;
+    fallbackPlacements?: TooltipPlacement[];
     className?: string;
     width?: string;
     dataTestId?: string;

package/lib/core/utils/index.d.ts

@@ -46,3 +46,4 @@ export * from './build-revision-url';
 export * from './content-segments';
 export * from './custom-catalog-options-casing';
 export * from './get-auto-dismiss-duration';
+export * from './tooltip-placement';

package/lib/core/utils/index.js

@@ -62,4 +62,5 @@ __exportStar(require("./build-revision-url"), exports);
 __exportStar(require("./content-segments"), exports);
 __exportStar(require("./custom-catalog-options-casing"), exports);
 __exportStar(require("./get-auto-dismiss-duration"), exports);
+__exportStar(require("./tooltip-placement"), exports);
 //# sourceMappingURL=index.js.map

package/lib/core/utils/tooltip-placement.d.ts

@@ -0,0 +1,32 @@
+import type { TooltipPlacement, TooltipProps } from '../../core/types';
+export declare function getDefaultFallbackPlacements(placement: TooltipPlacement): TooltipPlacement[];
+export declare function calcAnchorPoint(triggerRect: DOMRect, placement: TooltipPlacement, arrowPosition: TooltipProps['arrowPosition']): {
+    top: number;
+    left: number;
+};
+type FitsInViewportParams = {
+    anchor: {
+        top: number;
+        left: number;
+    };
+    tooltipWidth: number;
+    tooltipHeight: number;
+    placement: TooltipPlacement;
+    arrowPosition: TooltipProps['arrowPosition'];
+};
+export declare function fitsInViewport({ anchor, tooltipWidth, tooltipHeight, placement, arrowPosition, }: FitsInViewportParams): boolean;
+type ResolvePlacementParams = {
+    triggerRect: DOMRect;
+    tooltipWidth: number;
+    tooltipHeight: number;
+    placement: TooltipPlacement;
+    arrowPosition: TooltipProps['arrowPosition'];
+    fallbackPlacements: TooltipPlacement[] | undefined;
+};
+/**
+ * Given the trigger rect, tooltip dimensions, primary placement/arrow, and
+ * fallback list, returns the first placement that keeps the tooltip fully
+ * inside the viewport. Falls back to the primary when nothing fits.
+ */
+export declare function resolvePlacement({ triggerRect, tooltipWidth, tooltipHeight, placement, arrowPosition, fallbackPlacements, }: ResolvePlacementParams): TooltipPlacement;
+export {};

package/lib/core/utils/tooltip-placement.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDefaultFallbackPlacements = getDefaultFallbackPlacements;
+exports.calcAnchorPoint = calcAnchorPoint;
+exports.fitsInViewport = fitsInViewport;
+exports.resolvePlacement = resolvePlacement;
+const PLACEMENT_MARGIN = 10;
+const COUNTER_CLOCKWISE = ['top', 'left', 'bottom', 'right'];
+function getDefaultFallbackPlacements(placement) {
+    const index = COUNTER_CLOCKWISE.indexOf(placement);
+    const result = [];
+    for (let i = 1; i < COUNTER_CLOCKWISE.length; i++) {
+        result.push(COUNTER_CLOCKWISE[(index + i) % COUNTER_CLOCKWISE.length]);
+    }
+    return result;
+}
+function calcAnchorPoint(triggerRect, placement, arrowPosition) {
+    const horizontalLeft = () => arrowPosition === 'left'
+        ? triggerRect.left - 24
+        : arrowPosition === 'right'
+            ? triggerRect.right + 24
+            : triggerRect.left + triggerRect.width / 2;
+    const verticalTop = () => triggerRect.top + triggerRect.height / 2;
+    switch (placement) {
+        case 'top':
+            return { top: triggerRect.top, left: horizontalLeft() };
+        case 'bottom':
+            return { top: triggerRect.bottom, left: horizontalLeft() };
+        case 'left':
+            return { top: verticalTop(), left: triggerRect.left };
+        case 'right':
+            return { top: verticalTop(), left: triggerRect.right };
+    }
+}
+function fitsInViewport({ anchor, tooltipWidth, tooltipHeight, placement, arrowPosition, }) {
+    const horizontalLeft = () => arrowPosition === 'left'
+        ? anchor.left
+        : arrowPosition === 'right'
+            ? anchor.left - tooltipWidth
+            : anchor.left - tooltipWidth / 2;
+    const verticalTop = () => anchor.top - tooltipHeight / 2;
+    let top;
+    let left;
+    switch (placement) {
+        case 'top':
+            top = anchor.top - tooltipHeight - PLACEMENT_MARGIN;
+            left = horizontalLeft();
+            break;
+        case 'bottom':
+            top = anchor.top + PLACEMENT_MARGIN;
+            left = horizontalLeft();
+            break;
+        case 'left':
+            top = verticalTop();
+            left = anchor.left - tooltipWidth - PLACEMENT_MARGIN;
+            break;
+        case 'right':
+            top = verticalTop();
+            left = anchor.left + PLACEMENT_MARGIN;
+            break;
+    }
+    return (top >= 0 &&
+        left >= 0 &&
+        left + tooltipWidth <= window.innerWidth &&
+        top + tooltipHeight <= window.innerHeight);
+}
+/**
+ * Given the trigger rect, tooltip dimensions, primary placement/arrow, and
+ * fallback list, returns the first placement that keeps the tooltip fully
+ * inside the viewport. Falls back to the primary when nothing fits.
+ */
+function resolvePlacement({ triggerRect, tooltipWidth, tooltipHeight, placement, arrowPosition, fallbackPlacements, }) {
+    if (!(fallbackPlacements === null || fallbackPlacements === void 0 ? void 0 : fallbackPlacements.length) || tooltipWidth === 0 || tooltipHeight === 0) {
+        return placement;
+    }
+    const candidates = [placement, ...fallbackPlacements];
+    for (const candidate of candidates) {
+        const candidateArrow = candidate === placement ? arrowPosition : 'center';
+        const pos = calcAnchorPoint(triggerRect, candidate, candidateArrow);
+        if (fitsInViewport({
+            anchor: pos,
+            tooltipWidth,
+            tooltipHeight,
+            placement: candidate,
+            arrowPosition: candidateArrow,
+        })) {
+            return candidate;
+        }
+    }
+    return placement;
+}
+//# sourceMappingURL=tooltip-placement.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redocly/theme",
-  "version": "0.64.0",
+  "version": "0.65.0-next.0",
   "description": "Shared UI components lib",
   "keywords": [
     "theme",
@@ -63,7 +63,7 @@
     "vitest": "4.0.10",
     "vitest-when": "0.6.2",
     "webpack": "5.105.2",
-    "@redocly/realm-asyncapi-sdk": "0.10.0"
+    "@redocly/realm-asyncapi-sdk": "0.11.0-next.0"
   },
   "dependencies": {
     "@tanstack/react-query": "5.62.3",

package/src/components/Tooltip/AnchorTooltip.tsx

@@ -4,7 +4,11 @@ import styled, { css } from 'styled-components';
 import type { JSX, PropsWithChildren } from 'react';
 import type { TooltipProps } from '@redocly/theme/core/types';
 
-import { useControl, useOutsideClick } from '@redocly/theme/core/hooks';
+import {
+  useControl,
+  useOutsideClick,
+  useTooltipFallbackPlacement,
+} from '@redocly/theme/core/hooks';
 import { Portal } from '@redocly/theme/components/Portal/Portal';
 
 type Props = Exclude<TooltipProps, 'arrowPosition'> & {
@@ -17,6 +21,7 @@ function TooltipComponent({
   tip,
   withArrow = true,
   placement = 'top',
+  fallbackPlacements,
   className = 'default',
   width,
   dataTestId,
@@ -29,6 +34,14 @@ function TooltipComponent({
   const { isOpened, handleOpen, handleClose } = useControl(isOpen);
   const anchorName = `--tooltip${useId().replace(/:/g, '')}`;
 
+  const { activePlacement, activeArrowPosition } = useTooltipFallbackPlacement({
+    isOpened,
+    placement,
+    arrowPosition,
+    fallbackPlacements,
+    tooltipBodyRef,
+  });
+
   useOutsideClick(isOpened ? [tooltipWrapperRef, tooltipBodyRef] : tooltipWrapperRef, handleClose);
 
   const isControlled = isOpen !== undefined;
@@ -71,10 +84,14 @@ function TooltipComponent({
           <TooltipBody
             ref={tooltipBodyRef}
             data-testid={dataTestId || (typeof tip === 'string' ? tip : '')}
-            placement={placement}
+            placement={activePlacement}
             width={width}
             withArrow={withArrow}
-            arrowPosition={arrowPosition}
+            arrowPosition={
+              activeArrowPosition === 'left' || activeArrowPosition === 'right'
+                ? activeArrowPosition
+                : 'center'
+            }
             anchorName={anchorName}
           >
             {tip}

package/src/components/Tooltip/JsTooltip.tsx

@@ -6,6 +6,7 @@ import type { TooltipProps } from '@redocly/theme/core/types';
 
 import { useControl, useOutsideClick } from '@redocly/theme/core/hooks';
 import { Portal } from '@redocly/theme/components/Portal/Portal';
+import { calcAnchorPoint, resolvePlacement } from '@redocly/theme/core/utils';
 
 function TooltipComponent({
   children,
@@ -13,6 +14,7 @@ function TooltipComponent({
   tip,
   withArrow = true,
   placement = 'top',
+  fallbackPlacements,
   className = 'default',
   width,
   dataTestId,
@@ -20,58 +22,41 @@ function TooltipComponent({
   arrowPosition = 'center',
   onClick,
 }: PropsWithChildren<TooltipProps>): JSX.Element {
-  const ref = useRef<HTMLDivElement | null>(null);
+  const wrapperRef = useRef<HTMLDivElement | null>(null);
+  const tooltipBodyRef = useRef<HTMLSpanElement | null>(null);
   const { isOpened, handleOpen, handleClose } = useControl(isOpen);
   const [tooltipPosition, setTooltipPosition] = useState({ top: 0, left: 0 });
+  const [activePlacement, setActivePlacement] = useState(placement);
 
-  useOutsideClick(ref, handleClose);
+  const activeArrowPosition = activePlacement === placement ? arrowPosition : 'center';
+
+  useOutsideClick(wrapperRef, handleClose);
 
   const isControlled = isOpen !== undefined;
 
-  const updateTooltipPosition = useCallback(() => {
-    if (isOpened && ref.current) {
-      const rect = ref.current.getBoundingClientRect();
-
-      let top = 0;
-      let left = 0;
-
-      switch (placement) {
-        case 'top':
-          top = rect.top;
-          if (arrowPosition === 'left') {
-            left = rect.left - 24;
-          } else if (arrowPosition === 'right') {
-            left = rect.right + 24;
-          } else {
-            left = rect.left + rect.width / 2;
-          }
-          break;
-        case 'bottom':
-          top = rect.bottom;
-          if (arrowPosition === 'left') {
-            left = rect.left - 24;
-          } else if (arrowPosition === 'right') {
-            left = rect.right + 24;
-          } else {
-            left = rect.left + rect.width / 2;
-          }
-          break;
-        case 'left':
-          top = rect.top + rect.height / 2;
-          left = rect.left;
-          break;
-        case 'right':
-          top = rect.top + rect.height / 2;
-          left = rect.right;
-          break;
-      }
-
-      setTooltipPosition({ top, left });
-    }
-  }, [isOpened, placement, arrowPosition]);
+  const updateTooltipPosition = useCallback((): void => {
+    if (!isOpened || !wrapperRef.current) return;
+
+    const triggerRect = wrapperRef.current.getBoundingClientRect();
+    const tooltipWidth = tooltipBodyRef.current?.offsetWidth ?? 0;
+    const tooltipHeight = tooltipBodyRef.current?.offsetHeight ?? 0;
+
+    const resolved = resolvePlacement({
+      triggerRect,
+      tooltipWidth,
+      tooltipHeight,
+      placement,
+      arrowPosition,
+      fallbackPlacements,
+    });
+    const resolvedArrow = resolved === placement ? arrowPosition : 'center';
+
+    setTooltipPosition(calcAnchorPoint(triggerRect, resolved, resolvedArrow));
+    setActivePlacement(resolved);
+  }, [isOpened, placement, arrowPosition, fallbackPlacements]);
 
   useLayoutEffect(() => {
-    if (isOpened && ref.current) {
+    if (isOpened && wrapperRef.current) {
       updateTooltipPosition();
 
       const handleScroll = () => updateTooltipPosition();
@@ -109,7 +94,7 @@ function TooltipComponent({
 
   return (
     <TooltipWrapper
-      ref={ref}
+      ref={wrapperRef}
       {...controllers}
       className={`tooltip-${className}`}
       data-component-name="Tooltip/Tooltip"
@@ -118,11 +103,12 @@ function TooltipComponent({
       {isOpened && !disabled && (
         <Portal>
           <TooltipBody
+            ref={tooltipBodyRef}
             data-testid={dataTestId || (typeof tip === 'string' ? tip : '')}
-            placement={placement}
+            placement={activePlacement}
             width={width}
             withArrow={withArrow}
-            arrowPosition={arrowPosition}
+            arrowPosition={activeArrowPosition}
             style={{
               position: 'fixed',
               top: tooltipPosition.top,
@@ -255,7 +241,9 @@ const TooltipWrapper = styled.div`
   display: flex;
 `;
 const TooltipBody = styled.span<
-  Pick<Required<TooltipProps>, 'placement' | 'withArrow' | 'arrowPosition'> & { width?: string }
+  Pick<Required<TooltipProps>, 'placement' | 'withArrow' | 'arrowPosition'> & {
+    width?: string;
+  }
 >`
   display: inline-block;
 

package/src/components/Tooltip/Tooltip.tsx

@@ -1,18 +1,29 @@
 import React, { memo } from 'react';
 
+import type { TooltipProps } from '@redocly/theme/core/types';
+
 import { Tooltip as AnchorTooltip } from '@redocly/theme/components/Tooltip/AnchorTooltip';
 import { Tooltip as JsTooltip } from '@redocly/theme/components/Tooltip/JsTooltip';
-import { TooltipProps } from '@redocly/theme/core/types';
 import { useThemeHooks } from '@redocly/theme/core/hooks';
+import { getDefaultFallbackPlacements } from '@redocly/theme/core/utils';
 
 function TooltipComponent(props: TooltipProps): React.ReactElement {
   const { useAnchorPositioning } = useThemeHooks();
   const { isSupported } = useAnchorPositioning();
 
+  const fallbackPlacements =
+    props.fallbackPlacements ?? getDefaultFallbackPlacements(props.placement ?? 'top');
+
   if (isSupported) {
-    return <AnchorTooltip {...props} arrowPosition={prepareArrowPosition(props.arrowPosition)} />;
+    return (
+      <AnchorTooltip
+        {...props}
+        fallbackPlacements={fallbackPlacements}
+        arrowPosition={prepareArrowPosition(props.arrowPosition)}
+      />
+    );
   }
-  return <JsTooltip {...props} />;
+  return <JsTooltip {...props} fallbackPlacements={fallbackPlacements} />;
 }
 
 export const Tooltip = memo<TooltipProps>(TooltipComponent);

package/src/core/hooks/__mocks__/index.ts

@@ -26,3 +26,4 @@ export * from '../use-language-picker';
 export * from './use-element-size';
 export * from './use-time-ago';
 export * from './use-input-key-commands';
+export * from '../use-tooltip-fallback-placement';

package/src/core/hooks/index.ts

@@ -54,3 +54,4 @@ export * from './use-is-truncated';
 export * from './use-toast';
 export * from './use-toast-logic';
 export * from './use-banner-telemetry';
+export * from './use-tooltip-fallback-placement';

package/src/core/hooks/use-tooltip-fallback-placement.ts

@@ -0,0 +1,73 @@
+import { useLayoutEffect, useRef, useState } from 'react';
+
+import type { RefObject } from 'react';
+import type { TooltipPlacement, TooltipProps } from '@redocly/theme/core/types';
+
+type TooltipFallbackPlacementParams = {
+  isOpened: boolean;
+  placement: TooltipPlacement;
+  arrowPosition: TooltipProps['arrowPosition'];
+  fallbackPlacements: TooltipPlacement[] | undefined;
+  tooltipBodyRef: RefObject<HTMLElement | null>;
+};
+
+type TooltipFallbackPlacementResult = {
+  activePlacement: TooltipPlacement;
+  activeArrowPosition: TooltipProps['arrowPosition'];
+};
+
+export function useTooltipFallbackPlacement({
+  isOpened,
+  placement,
+  arrowPosition,
+  fallbackPlacements,
+  tooltipBodyRef,
+}: TooltipFallbackPlacementParams): TooltipFallbackPlacementResult {
+  const [activePlacement, setActivePlacement] = useState<TooltipPlacement>(placement);
+  const wasOpenRef = useRef(false);
+  const candidateIndexRef = useRef(0);
+
+  useLayoutEffect(() => {
+    if (!isOpened) {
+      wasOpenRef.current = false;
+      candidateIndexRef.current = 0;
+      return;
+    }
+
+    if (!wasOpenRef.current) {
+      wasOpenRef.current = true;
+      candidateIndexRef.current = 0;
+      if (activePlacement !== placement) {
+        setActivePlacement(placement);
+        return;
+      }
+    }
+
+    if (!tooltipBodyRef.current || !fallbackPlacements?.length) return;
+
+    const candidates: TooltipPlacement[] = [placement, ...fallbackPlacements];
+
+    if (candidateIndexRef.current >= candidates.length) return;
+
+    const rect = tooltipBodyRef.current.getBoundingClientRect();
+    const overflows =
+      rect.left < 0 ||
+      rect.top < 0 ||
+      rect.right > window.innerWidth ||
+      rect.bottom > window.innerHeight;
+
+    if (!overflows) return;
+
+    candidateIndexRef.current++;
+
+    if (candidateIndexRef.current < candidates.length) {
+      setActivePlacement(candidates[candidateIndexRef.current]);
+    } else if (activePlacement !== placement) {
+      setActivePlacement(placement);
+    }
+  }, [isOpened, activePlacement, placement, fallbackPlacements, tooltipBodyRef]);
+
+  const activeArrowPosition = activePlacement === placement ? arrowPosition : 'center';
+
+  return { activePlacement, activeArrowPosition };
+}

package/src/core/styles/global.ts

@@ -1253,6 +1253,7 @@ const replay = css`
   --replay-runtime-expression-color: rgba(54, 90, 249, 1); // @presenter Color
   --replay-runtime-expression-bg-color: rgba(54, 90, 249, 0.08); // @presenter Color
   --replay-operators-color: rgba(193, 142, 31, 1); // @presenter Color
+  --replay-claude-icon-color: rgba(217, 119, 87, 1); // @presenter Color
 
   --replay-ai-gradient-soft: linear-gradient(62.6deg, rgba(113, 94, 254, 0.16) 0%, rgba(255, 92, 220, 0.16) 100%);
   --replay-ai-gradient-disabled: linear-gradient(62.6deg, rgba(113, 94, 254, 0.6) 0%, rgba(255, 92, 220, 0.6) 100%);

package/src/core/types/tooltip.ts

@@ -1,11 +1,14 @@
 import type { ReactNode } from 'react';
 
+export type TooltipPlacement = 'top' | 'bottom' | 'left' | 'right';
+
 export type TooltipProps = {
   children?: ReactNode;
   tip: string | ReactNode;
   isOpen?: boolean;
   withArrow?: boolean;
-  placement?: 'top' | 'bottom' | 'left' | 'right';
+  placement?: TooltipPlacement;
+  fallbackPlacements?: TooltipPlacement[];
   className?: string;
   width?: string;
   dataTestId?: string;

package/src/core/utils/index.ts

@@ -46,3 +46,4 @@ export * from './build-revision-url';
 export * from './content-segments';
 export * from './custom-catalog-options-casing';
 export * from './get-auto-dismiss-duration';
+export * from './tooltip-placement';

package/src/core/utils/tooltip-placement.ts

@@ -0,0 +1,141 @@
+import type { TooltipPlacement, TooltipProps } from '@redocly/theme/core/types';
+
+const PLACEMENT_MARGIN = 10;
+const COUNTER_CLOCKWISE: TooltipPlacement[] = ['top', 'left', 'bottom', 'right'];
+
+export function getDefaultFallbackPlacements(placement: TooltipPlacement): TooltipPlacement[] {
+  const index = COUNTER_CLOCKWISE.indexOf(placement);
+  const result: TooltipPlacement[] = [];
+  for (let i = 1; i < COUNTER_CLOCKWISE.length; i++) {
+    result.push(COUNTER_CLOCKWISE[(index + i) % COUNTER_CLOCKWISE.length]);
+  }
+  return result;
+}
+
+export function calcAnchorPoint(
+  triggerRect: DOMRect,
+  placement: TooltipPlacement,
+  arrowPosition: TooltipProps['arrowPosition'],
+): { top: number; left: number } {
+  const horizontalLeft = (): number =>
+    arrowPosition === 'left'
+      ? triggerRect.left - 24
+      : arrowPosition === 'right'
+        ? triggerRect.right + 24
+        : triggerRect.left + triggerRect.width / 2;
+
+  const verticalTop = (): number => triggerRect.top + triggerRect.height / 2;
+
+  switch (placement) {
+    case 'top':
+      return { top: triggerRect.top, left: horizontalLeft() };
+    case 'bottom':
+      return { top: triggerRect.bottom, left: horizontalLeft() };
+    case 'left':
+      return { top: verticalTop(), left: triggerRect.left };
+    case 'right':
+      return { top: verticalTop(), left: triggerRect.right };
+  }
+}
+
+type FitsInViewportParams = {
+  anchor: { top: number; left: number };
+  tooltipWidth: number;
+  tooltipHeight: number;
+  placement: TooltipPlacement;
+  arrowPosition: TooltipProps['arrowPosition'];
+};
+
+export function fitsInViewport({
+  anchor,
+  tooltipWidth,
+  tooltipHeight,
+  placement,
+  arrowPosition,
+}: FitsInViewportParams): boolean {
+  const horizontalLeft = (): number =>
+    arrowPosition === 'left'
+      ? anchor.left
+      : arrowPosition === 'right'
+        ? anchor.left - tooltipWidth
+        : anchor.left - tooltipWidth / 2;
+
+  const verticalTop = (): number => anchor.top - tooltipHeight / 2;
+
+  let top: number;
+  let left: number;
+
+  switch (placement) {
+    case 'top':
+      top = anchor.top - tooltipHeight - PLACEMENT_MARGIN;
+      left = horizontalLeft();
+      break;
+    case 'bottom':
+      top = anchor.top + PLACEMENT_MARGIN;
+      left = horizontalLeft();
+      break;
+    case 'left':
+      top = verticalTop();
+      left = anchor.left - tooltipWidth - PLACEMENT_MARGIN;
+      break;
+    case 'right':
+      top = verticalTop();
+      left = anchor.left + PLACEMENT_MARGIN;
+      break;
+  }
+
+  return (
+    top >= 0 &&
+    left >= 0 &&
+    left + tooltipWidth <= window.innerWidth &&
+    top + tooltipHeight <= window.innerHeight
+  );
+}
+
+type ResolvePlacementParams = {
+  triggerRect: DOMRect;
+  tooltipWidth: number;
+  tooltipHeight: number;
+  placement: TooltipPlacement;
+  arrowPosition: TooltipProps['arrowPosition'];
+  fallbackPlacements: TooltipPlacement[] | undefined;
+};
+
+/**
+ * Given the trigger rect, tooltip dimensions, primary placement/arrow, and
+ * fallback list, returns the first placement that keeps the tooltip fully
+ * inside the viewport. Falls back to the primary when nothing fits.
+ */
+export function resolvePlacement({
+  triggerRect,
+  tooltipWidth,
+  tooltipHeight,
+  placement,
+  arrowPosition,
+  fallbackPlacements,
+}: ResolvePlacementParams): TooltipPlacement {
+  if (!fallbackPlacements?.length || tooltipWidth === 0 || tooltipHeight === 0) {
+    return placement;
+  }
+
+  const candidates: TooltipPlacement[] = [placement, ...fallbackPlacements];
+
+  for (const candidate of candidates) {
+    const candidateArrow = candidate === placement ? arrowPosition : 'center';
+    const pos = calcAnchorPoint(triggerRect, candidate, candidateArrow);
+
+    if (
+      fitsInViewport({
+        anchor: pos,
+        tooltipWidth,
+        tooltipHeight,
+        placement: candidate,
+        arrowPosition: candidateArrow,
+      })
+    ) {
+      return candidate;
+    }
+  }
+
+  return placement;
+}