@ncds/ui-admin 1.8.4 → 1.8.5

package/dist/esm/src/components/forms-and-input/select-box/SelectBox.js

@@ -2,8 +2,11 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 import { ChevronDown } from '@ncds/ui-admin-icon';
 import classNames from 'classnames';
 import { forwardRef, useCallback, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
 import { COLOR } from '../../../../constant/color';
 import { useDropdown, useScrollLock } from '../../../hooks/dropdown';
+import { useFloatingPosition } from '../../../hooks/useFloatingPosition';
+import { usePortalState } from '../../../hooks/usePortalState';
 import { useMultiSelect } from '../../../utils/dropdown/multiSelect';
 import { Tag } from '../../feedback-and-status/tag';
 import { SelectDropdown } from '../../select-dropdown';
@@ -54,7 +57,9 @@ function DisplayValue(_ref) {
     })]
   });
 }
-const SelectBox = /*#__PURE__*/forwardRef((_ref2, ref) => {
+const SelectBox = /*#__PURE__*/forwardRef((_ref2, ref
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: 옵션/멀티/태그/포탈 등 필수 분기 통합
+) => {
   let {
     placeholder = '선택하세요',
     disabledPlaceholder = false,
@@ -68,7 +73,9 @@ const SelectBox = /*#__PURE__*/forwardRef((_ref2, ref) => {
     disabled = false,
     maxHeight = DEFAULT_MAX_HEIGHT,
     multiple = false,
+    maxSelection,
     align = 'left',
+    usePortal,
     id,
     className,
     children,
@@ -79,6 +86,10 @@ const SelectBox = /*#__PURE__*/forwardRef((_ref2, ref) => {
   } = _ref2;
   const internalRef = useRef(null);
   const dropdownRef = useRef(null);
+  const {
+    shouldPortal,
+    portalContainer
+  } = usePortalState(usePortal);
   const [selectedTags, setSelectedTags] = useState([]);
   const selectedOption = useMemo(() => {
     if (multiple) return null;
@@ -92,6 +103,13 @@ const SelectBox = /*#__PURE__*/forwardRef((_ref2, ref) => {
   }, [multiple, selectedOption, placeholder]);
   const handleOptionSelect = option => {
     if (disabled) return;
+    if (multiple) {
+      const newValue = tryToggle(option.id, Array.isArray(value) ? value : []);
+      if (newValue === null) return;
+      onChange?.(newValue);
+      notifyRegister(register, newValue, multiple);
+      return;
+    }
     const newValue = computeNewValue(option, value, multiple);
     onChange?.(newValue);
     notifyRegister(register, newValue, multiple);
@@ -134,8 +152,12 @@ const SelectBox = /*#__PURE__*/forwardRef((_ref2, ref) => {
     buttonText: selectAllButtonText,
     toggleSelectAll,
     getSelectedTagsData,
-    removeTag
-  } = useMultiSelect(currentSelectedValues, optionItems);
+    removeTag,
+    isMaxSelectionActive,
+    tryToggle
+  } = useMultiSelect(currentSelectedValues, optionItems, {
+    maxSelection
+  });
   const handleSelectAll = () => {
     if (!multiple || !onChange) return;
     const newSelectedValues = toggleSelectAll();
@@ -160,13 +182,53 @@ const SelectBox = /*#__PURE__*/forwardRef((_ref2, ref) => {
     }
   };
   useScrollLock(isOpen, dropdownRef);
+  // biome-ignore lint/correctness/useExhaustiveDependencies: optionItems 변경 시 너비 재계산 필요
   useLayoutEffect(() => {
     if (autoWidth && isOpen && dropdownRef.current && internalRef.current) {
       const dropdownWidth = dropdownRef.current.offsetWidth;
       internalRef.current.style.width = `${dropdownWidth}px`;
     }
   }, [autoWidth, isOpen, optionItems]);
+  const floatingStyle = useFloatingPosition({
+    enabled: shouldPortal,
+    isOpen,
+    triggerRef: internalRef,
+    floatingRef: dropdownRef,
+    direction: dropdownDirection,
+    align,
+    matchTriggerWidth: true
+  });
+  // biome-ignore lint/style/noNonNullAssertion: forwardRef 패턴에서 internalRef는 항상 존재
   useImperativeHandle(ref, () => internalRef.current, []);
+  const selectDropdownNode = _jsx(SelectDropdown, {
+    ref: dropdownRef,
+    isOpen: isOpen,
+    direction: dropdownDirection,
+    size: size,
+    options: optionItems,
+    value: value,
+    focusedIndex: focusedIndex,
+    maxHeight: maxHeight,
+    listboxId: `selectbox-options-${id || 'default'}`,
+    multiple: multiple,
+    showFooterButtons: multiple,
+    selectAllButtonText: selectAllButtonText,
+    showSelectAllAction: !isMaxSelectionActive,
+    componentType: "selectbox",
+    isKeyboardNavigation: isKeyboardNavigation,
+    activeDescendantId: activeDescendantId,
+    align: align,
+    className: shouldPortal ? 'ncua-select-dropdown--portal' : undefined,
+    style: shouldPortal && floatingStyle ? floatingStyle : undefined,
+    onOptionSelect: handleDropdownSelect,
+    onMouseMove: handleMouseMove,
+    onOptionHover: handleOptionHover,
+    onSelectAll: handleSelectAll,
+    onEdit: handleEdit,
+    onComplete: handleComplete,
+    children: children
+  });
+  const portaledDropdown = shouldPortal && portalContainer && isOpen ? /*#__PURE__*/createPortal(selectDropdownNode, portalContainer) : null;
   return _jsxs(_Fragment, {
     children: [_jsxs("div", {
       ref: internalRef,
@@ -205,31 +267,7 @@ const SelectBox = /*#__PURE__*/forwardRef((_ref2, ref) => {
               'ncua-selectbox__arrow--up': isOpen
             })
           })]
-        }), _jsx(SelectDropdown, {
-          ref: dropdownRef,
-          isOpen: isOpen,
-          direction: dropdownDirection,
-          size: size,
-          options: optionItems,
-          value: value,
-          focusedIndex: focusedIndex,
-          maxHeight: maxHeight,
-          listboxId: `selectbox-options-${id || 'default'}`,
-          multiple: multiple,
-          showFooterButtons: multiple,
-          selectAllButtonText: selectAllButtonText,
-          componentType: "selectbox",
-          isKeyboardNavigation: isKeyboardNavigation,
-          activeDescendantId: activeDescendantId,
-          align: align,
-          onOptionSelect: handleDropdownSelect,
-          onMouseMove: handleMouseMove,
-          onOptionHover: handleOptionHover,
-          onSelectAll: handleSelectAll,
-          onEdit: handleEdit,
-          onComplete: handleComplete,
-          children: children
-        })]
+        }), !shouldPortal && selectDropdownNode]
       }), hintText && _jsx(HintText, {
         destructive: destructive,
         className: "ncua-hint-text",
@@ -247,7 +285,7 @@ const SelectBox = /*#__PURE__*/forwardRef((_ref2, ref) => {
         close: true,
         onButtonClick: () => handleRemoveTag(tag.id)
       }, tag.id))
-    })]
+    }), portaledDropdown]
   });
 });
 SelectBox.displayName = 'SelectBox';

package/dist/esm/src/components/overlays/dropdown/Dropdown.js

@@ -7,6 +7,9 @@ import { autoScrollForElements } from '@atlaskit/pragmatic-drag-and-drop-auto-sc
 import { attachClosestEdge, extractClosestEdge } from '@atlaskit/pragmatic-drag-and-drop-hitbox/closest-edge';
 import { DotsGrid02, DotsVertical, Eye, EyeOff } from '@ncds/ui-admin-icon';
 import { useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { useFloatingPosition } from '../../../hooks/useFloatingPosition';
+import { usePortalState } from '../../../hooks/usePortalState';
 import { Button } from '../../action/button';
 import { applyDraftToItems, arrayReorderByEdge, hasDraftChanged, initDraftState } from './utils';
 const DROPDOWN_ID_RADIX = 36;
@@ -143,6 +146,7 @@ const SortableConfigItem = _ref => {
     })]
   });
 };
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: 액션/설정 두 variant 통합 + drag-and-drop 필수 분기
 export const Dropdown = props => {
   const {
     trigger,
@@ -151,14 +155,28 @@ export const Dropdown = props => {
     groups,
     className,
     opened = false,
-    closeOnClickOutside = true
+    closeOnClickOutside = true,
+    usePortal
   } = props;
   const variant = props.variant ?? 'action';
   const closeOnClickItem = variant === 'action' ? props.closeOnClickItem ?? true : false;
   const [isOpen, setIsOpen] = useState(opened);
   const dropdownRef = useRef(null);
   const triggerRef = useRef(null);
+  const menuRef = useRef(null);
   const menuItemsRef = useRef(null);
+  const {
+    shouldPortal,
+    portalContainer
+  } = usePortalState(usePortal);
+  const floatingStyle = useFloatingPosition({
+    enabled: shouldPortal,
+    isOpen,
+    triggerRef,
+    floatingRef: menuRef,
+    direction: 'down',
+    align
+  });
   const dropdownIdRef = useRef(`ncua-dropdown-${Math.random().toString(DROPDOWN_ID_RADIX).slice(DROPDOWN_ID_SLICE_START, DROPDOWN_ID_SLICE_END)}`);
   const dropdownId = dropdownIdRef.current;
   useEffect(() => {
@@ -221,7 +239,10 @@ export const Dropdown = props => {
     triggerRef.current?.focus();
   };
   const handleClickOutside = event => {
-    if (dropdownRef.current && !dropdownRef.current.contains(event.target)) {
+    const target = event.target;
+    const insideContainer = dropdownRef.current?.contains(target) ?? false;
+    const insidePortaledMenu = menuRef.current?.contains(target) ?? false;
+    if (!insideContainer && !insidePortaledMenu) {
       setIsOpen(false);
     }
   };
@@ -233,6 +254,7 @@ export const Dropdown = props => {
       }
     }
   };
+  // biome-ignore lint/correctness/useExhaustiveDependencies: handleClickOutside는 안정적 참조
   useEffect(() => {
     if (closeOnClickOutside) {
       document.addEventListener('mousedown', handleClickOutside);
@@ -242,6 +264,7 @@ export const Dropdown = props => {
     }
   }, [closeOnClickOutside]);
   // ESC 키로 닫고 trigger로 포커스 복귀
+  // biome-ignore lint/correctness/useExhaustiveDependencies: closeAndRestoreFocus는 안정적 참조
   useEffect(() => {
     if (!isOpen) return;
     const handleEsc = event => {
@@ -422,25 +445,30 @@ export const Dropdown = props => {
     });
   };
   const dropdownClasses = ['ncua-dropdown', className, align === 'right' ? 'ncua-dropdown--right' : ''].filter(Boolean).join(' ');
+  const menuClasses = ['ncua-dropdown__menu', shouldPortal ? 'ncua-dropdown__menu--portal' : ''].filter(Boolean).join(' ');
+  const menuNode = isOpen ? _jsxs("div", {
+    ref: menuRef,
+    className: menuClasses,
+    role: variant === 'config' ? 'dialog' : 'menu',
+    "aria-label": variant === 'config' ? '설정' : undefined,
+    style: shouldPortal && floatingStyle ? floatingStyle : undefined,
+    children: [renderHeader(), _jsx("div", {
+      ref: menuItemsRef,
+      className: "ncua-dropdown__menu-items",
+      children: groups.map(group => {
+        // config variant uses draft.order to drive the rendered order
+        const orderedItems = variant === 'config' && draft ? draft.order.map(id => group.items.find(i => i.id === id)).filter(i => i !== undefined) : group.items;
+        return _jsx("div", {
+          className: "ncua-dropdown__group",
+          children: orderedItems.map(item => variant === 'config' ? renderConfigItem(item, group.sortable === true) : renderActionItem(item))
+        }, group.items[0]?.id);
+      })
+    }), renderFooter()]
+  }) : null;
+  const portaledMenu = shouldPortal && portalContainer && menuNode ? /*#__PURE__*/createPortal(menuNode, portalContainer) : null;
   return _jsxs("div", {
     className: dropdownClasses,
     ref: dropdownRef,
-    children: [renderTrigger(), isOpen && _jsxs("div", {
-      className: "ncua-dropdown__menu",
-      role: variant === 'config' ? 'dialog' : 'menu',
-      "aria-label": variant === 'config' ? '설정' : undefined,
-      children: [renderHeader(), _jsx("div", {
-        ref: menuItemsRef,
-        className: "ncua-dropdown__menu-items",
-        children: groups.map(group => {
-          // config variant uses draft.order to drive the rendered order
-          const orderedItems = variant === 'config' && draft ? draft.order.map(id => group.items.find(i => i.id === id)).filter(i => i !== undefined) : group.items;
-          return _jsx("div", {
-            className: "ncua-dropdown__group",
-            children: orderedItems.map(item => variant === 'config' ? renderConfigItem(item, group.sortable === true) : renderActionItem(item))
-          }, group.items[0]?.id);
-        })
-      }), renderFooter()]
-    })]
+    children: [renderTrigger(), !shouldPortal && menuNode, portaledMenu]
   });
 };

package/dist/esm/src/components/overlays/notification/CalloutNotification.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import classNames from 'classnames';
+import { forwardRef } from 'react';
+const CalloutNotification = /*#__PURE__*/forwardRef((_ref, ref) => {
+  let {
+    color = 'neutral',
+    className,
+    title,
+    ...rest
+  } = _ref;
+  return _jsx("div", {
+    ref: ref,
+    className: classNames('ncua-callout-notification', `ncua-callout-notification--${color}`, className),
+    ...rest,
+    children: title
+  });
+});
+CalloutNotification.displayName = 'CalloutNotification';
+export { CalloutNotification };

package/dist/esm/src/components/overlays/notification/FloatingNotification.js

@@ -1,19 +1,64 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { AlertCircle, AlertTriangle, CheckCircle, Pin02 } from '@ncds/ui-admin-icon';
 import classNames from 'classnames';
-import { forwardRef, useEffect, useRef, useState } from 'react';
+import { forwardRef, useEffect, useId, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
 import { MEDIA_QUERY } from '../../../constant/breakpoint';
 import { useMediaQuery } from '../../../hooks/useMediaQuery';
 import { Button } from '../../action/button';
 import { ButtonCloseX } from '../../action/button/ButtonCloseX';
 import { FeaturedIcon } from '../../image-and-icons/featured-icon/FeaturedIcon';
+// 호스트 싱글톤은 vanilla/React 양쪽이 동일한 함수를 공유한다 — host.ts 가 가까운 진입점 역할을
+// 하므로 React 컴포넌트는 deep relative path 로 vanilla internals 를 직접 import 하지 않는다.
+import { mountFloatingNotificationHost } from './host';
+/**
+ * 색상별 a11y role.
+ *   - error/warning → role="alert"  (implicit aria-live="assertive": 즉시 발화)
+ *   - 그 외       → role="status" (implicit aria-live="polite": 현재 발화 끝난 후 발화)
+ * role 이 implicit live-region 을 가져오므로 호스트 컨테이너에는 aria-live 를 두지 않는다.
+ */
+const ASSERTIVE_COLORS = {
+  error: true,
+  warning: true
+};
 const iconMap = {
   neutral: Pin02,
   error: AlertTriangle,
   warning: AlertCircle,
   success: CheckCircle
-  // info는 floating에서는 지원하지 않음
+  // info 는 full-width 전용이라 floating 아이콘 매핑 없음.
+};
+/**
+ * NotificationColor → FeaturedIconColor 매핑.
+ * `info` 는 FeaturedIconColor 에 존재하지 않으므로 `neutral` 로 안전 fallback.
+ * `satisfies` 가 매핑 누락을 컴파일 타임에 강제하므로 향후 색상이 추가되면 즉시 타입 에러로 잡힌다.
+ */
+const iconColorMap = {
+  neutral: 'neutral',
+  error: 'error',
+  warning: 'warning',
+  success: 'success',
+  info: 'neutral'
 };
+/**
+ * `.ncua-floating-notification-host` 싱글톤을 보장하고 반환하는 훅.
+ *
+ * 이름의 `useMount...` 는 단순 조회가 아닌 **DOM 부수효과** 를 동반함을 신호한다 —
+ * 내부적으로 `mountFloatingNotificationHost()` 를 호출해 document.body 에 호스트를 append 하고
+ * (없으면) 글로벌 scroll/resize/MutationObserver 까지 부착한다. 호스트는 페이지 lifetime
+ * 싱글톤이므로 언마운트 시 제거하지 않는다.
+ *
+ * `mountFloatingNotificationHost` 는 **동기 함수** 이므로 effect 안의 호출 → setHost 가 같은 tick
+ * 에 끝나 cancellation race 가 없다. cancel flag 는 의미 없어 두지 않는다.
+ */
+function useMountFloatingNotificationHost(enabled) {
+  const [host, setHost] = useState(null);
+  useEffect(() => {
+    if (!enabled) return;
+    setHost(mountFloatingNotificationHost());
+  }, [enabled]);
+  return host;
+}
 const FloatingNotification = /*#__PURE__*/forwardRef((_ref, ref) => {
   let {
     title,
@@ -23,49 +68,65 @@ const FloatingNotification = /*#__PURE__*/forwardRef((_ref, ref) => {
     className,
     actions,
     autoClose = 0,
+    portal = false,
     ...rest
   } = _ref;
   const [shouldRemove, setShouldRemove] = useState(false);
-  const iconColor = color;
   const featuredIconProps = {
     icon: iconMap[color] || Pin02,
     size: 'sm',
-    color: iconColor,
+    color: iconColorMap[color],
     theme: 'dark-circle'
   };
   const isMobile = useMediaQuery(MEDIA_QUERY.mobile, {
     onMatched: onClose
   });
+  // onClose 는 매 렌더 새 함수 ref 일 수 있으므로 ref 로 latest 만 보관.
+  // → autoClose 타이머 effect 의 deps 에서 onClose 를 빼서 타이머 재시작 회피.
+  // render 본문에서 직접 할당 — useEffect 로 미루면 같은 commit 안에서 fire 되는 타이머가 stale onClose 를 볼 위험.
+  const onCloseRef = useRef(onClose);
+  onCloseRef.current = onClose;
   // autoClose 타이머 관리
   const timerRef = useRef(null);
+  // onClose 는 onCloseRef 로 latest 만 추적하므로 deps 에서 제외 (의도된 패턴).
   useEffect(() => {
-    // autoClose가 0보다 크면 무조건 타이머 설정
+    // autoClose 가 0 보다 크면 타이머 설정.
     if (autoClose > 0) {
       timerRef.current = setTimeout(() => {
-        if (onClose) {
-          onClose();
-        }
-        // DOM에서 바로 제거
+        onCloseRef.current?.();
+        // DOM 에서 바로 제거
         setShouldRemove(true);
       }, autoClose);
     }
-    // cleanup 함수: 컴포넌트 언마운트 시 타이머 정리
+    // cleanup: 컴포넌트 언마운트 또는 autoClose 변경 시 타이머 정리
     return () => {
       if (timerRef.current) {
         clearTimeout(timerRef.current);
         timerRef.current = null;
       }
     };
-  }, [autoClose, onClose]);
+  }, [autoClose]);
+  // portal=true 일 때만 호스트가 필요하다.
+  const host = useMountFloatingNotificationHost(portal);
+  // a11y — 카드 root 의 role 과 제목/본문 ID. 색상에 따라 alert(error/warning) / status(나머지) 로 분기.
+  const reactId = useId();
+  const titleId = `${reactId}-title`;
+  const descId = `${reactId}-desc`;
+  const role = ASSERTIVE_COLORS[color] ? 'alert' : 'status';
   // DOM에서 완전히 제거
   if (shouldRemove) {
     return null;
   }
-  return _jsxs("div", {
+  const card =
+  // a11y/예측가능성 — caller 가 className/id 등 일부는 덮어쓸 수 있게 {...rest} 를 먼저 펼치고,
+  // role/aria-labelledby/aria-describedby 같은 컴포넌트 본질 prop 은 그 뒤에 두어 우선 적용.
+  _jsxs("div", {
+    ...rest,
     ref: ref,
     className: classNames('ncua-floating-notification', `ncua-floating-notification--${color}`, className),
-    role: "alert",
-    ...rest,
+    role: role,
+    "aria-labelledby": titleId,
+    "aria-describedby": supportingText ? descId : undefined,
     children: [_jsx("div", {
       className: "ncua-floating-notification__content",
       children: _jsxs("div", {
@@ -78,10 +139,12 @@ const FloatingNotification = /*#__PURE__*/forwardRef((_ref, ref) => {
           children: [_jsx("div", {
             className: "ncua-floating-notification__title-wrapper",
             children: _jsx("span", {
+              id: titleId,
               className: "ncua-floating-notification__title",
               children: title
             })
           }), supportingText && _jsx("span", {
+            id: descId,
             className: "ncua-floating-notification__supporting-text",
             children: supportingText
           }), actions && _jsx("div", {
@@ -102,5 +165,14 @@ const FloatingNotification = /*#__PURE__*/forwardRef((_ref, ref) => {
       onClick: onClose
     })]
   });
+  // 기본은 인라인 렌더 — 부모 JSX 트리에 카드를 그대로 둔다.
+  if (!portal) {
+    return card;
+  }
+  // portal=true 인데 SSR이거나 첫 렌더(호스트 미생성)에서는 null. useEffect 후 host 설정되면 재렌더되어 portal 마운트.
+  if (!host) {
+    return null;
+  }
+  return /*#__PURE__*/createPortal(card, host);
 });
 export { FloatingNotification };

package/dist/esm/src/components/overlays/notification/Notification.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { forwardRef } from 'react';
+import { CalloutNotification } from './CalloutNotification';
 import { FloatingNotification } from './FloatingNotification';
 import { FullWidthNotification } from './FullWidthNotification';
 import { MessageNotification } from './MessageNotification';
@@ -30,6 +31,12 @@ const Notification = /*#__PURE__*/forwardRef((_ref, ref) => {
       ref: ref
     });
   }
+  if (type === 'callout') {
+    return _jsx(CalloutNotification, {
+      color: color,
+      ...rest
+    });
+  }
   return null;
 });
 Notification.displayName = 'Notification';

package/dist/esm/src/components/overlays/notification/host.js

@@ -0,0 +1,9 @@
+/**
+ * Floating Notification 호스트 관리 — React 측 진입점.
+ *
+ * 실제 구현은 vanilla/React 가 공유하는 `assets/scripts/notification/positionSync.ts` 에 있고,
+ * 외부 노출은 그 폴더의 public barrel(`assets/scripts/notification/index.ts`)이 담당한다.
+ * 이 모듈은 React 컴포넌트가 vanilla 내부 파일을 직접 참조하지 않도록 barrel 을 경유하는
+ * 한 단계 re-export 만 제공한다 — positionSync.ts 의 위치/이름이 바뀌어도 host.ts 만 영향.
+ */
+export { mountFloatingNotificationHost } from '../../../../assets/scripts/notification';

package/dist/esm/src/components/overlays/tooltip/Tooltip.js

@@ -1,4 +1,4 @@
-import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { AlertCircle, AlertCircleFill, HelpCircle, HelpCircleFill } from '@ncds/ui-admin-icon';
 import classNames from 'classnames';
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
@@ -70,6 +70,42 @@ const computePanelCoords = (prefer, anchor, panel) => {
     calculatedPosition
   };
 };
+const buildPanelStyle = (disablePortal, coords, visible, zIndex) => {
+  const opacity = visible ? 1 : 0;
+  if (disablePortal) return {
+    opacity
+  };
+  return {
+    top: `${coords.top}px`,
+    left: `${coords.left}px`,
+    opacity,
+    ...(zIndex && {
+      zIndex
+    })
+  };
+};
+const renderIcon = (iconStyle, iconType, iconSize, iconColor) => {
+  if (iconStyle === 'help-circle') {
+    return iconType === 'stroke' ? _jsx(HelpCircle, {
+      width: iconSize,
+      height: iconSize,
+      color: iconColor
+    }) : _jsx(HelpCircleFill, {
+      width: iconSize,
+      height: iconSize,
+      color: iconColor
+    });
+  }
+  return iconType === 'stroke' ? _jsx(AlertCircle, {
+    width: iconSize,
+    height: iconSize,
+    color: iconColor
+  }) : _jsx(AlertCircleFill, {
+    width: iconSize,
+    height: iconSize,
+    color: iconColor
+  });
+};
 export const Tooltip = _ref => {
   let {
     tooltipType = 'white',
@@ -83,7 +119,9 @@ export const Tooltip = _ref => {
     iconColor = 'var(--gray-300)',
     iconStyle = 'help-circle',
     className,
-    zIndex
+    zIndex,
+    forceVisible,
+    disablePortal = false
   } = _ref;
   const iconSize = size === 'sm' ? ICON_SIZE_SM : ICON_SIZE_DEFAULT;
   const anchorRef = useRef(null);
@@ -97,6 +135,7 @@ export const Tooltip = _ref => {
   const [calculatedPosition, setCalculatedPosition] = useState(position === 'auto' ? 'bottom' : position);
   const [isVisible, setIsVisible] = useState(false);
   const [isManuallyClose, setIsManuallyClose] = useState(false);
+  const effectiveVisible = forceVisible ?? isVisible;
   useEffect(() => {
     setMounted(true);
     return () => {
@@ -107,7 +146,7 @@ export const Tooltip = _ref => {
     };
   }, []);
   const updatePosition = useCallback(() => {
-    if (!anchorRef.current || !panelRef.current) return;
+    if (disablePortal || !anchorRef.current || !panelRef.current) return;
     const anchor = anchorRef.current.getBoundingClientRect();
     const panel = panelRef.current.getBoundingClientRect();
     const next = computePanelCoords(position, anchor, panel);
@@ -116,9 +155,9 @@ export const Tooltip = _ref => {
       left: next.left
     });
     setCalculatedPosition(next.calculatedPosition);
-  }, [position]);
+  }, [position, disablePortal]);
   useEffect(() => {
-    if (!isVisible) return;
+    if (!effectiveVisible || disablePortal) return;
     updatePosition();
     window.addEventListener('resize', updatePosition, {
       passive: true
@@ -133,13 +172,10 @@ export const Tooltip = _ref => {
         capture: true
       });
     };
-  }, [isVisible, updatePosition]);
+  }, [effectiveVisible, updatePosition, disablePortal]);
   const handleMouseEnter = useCallback(() => {
     if (isManuallyClose) return;
-    // opacity 전환 전에 좌표 확정 (ref 가드는 updatePosition 내부)
     updatePosition();
-    // 웹폰트 로드·max-content 재계산 등 비동기 layout 안정화 후 한 번 더 보정
-    // 빠른 hover in/out 시 이전 프레임 요청은 취소해 중복/unmount 후 실행 방지
     if (rafIdRef.current !== null) cancelAnimationFrame(rafIdRef.current);
     rafIdRef.current = requestAnimationFrame(() => {
       rafIdRef.current = null;
@@ -163,18 +199,13 @@ export const Tooltip = _ref => {
     'ncua-tooltip--stroke': iconType === 'stroke',
     'ncua-tooltip--auto': position === 'auto'
   }, className), [size, type, hideArrow, iconType, position, className]);
-  const panelClassName = useMemo(() => classNames('ncua-tooltip-panel', 'ncua-tooltip__bg', `ncua-tooltip__bg--${tooltipType}`, `ncua-tooltip__bg--${finalPosition}`, {
-    'ncua-tooltip__bg--visible': isVisible,
-    'ncua-tooltip__bg--force-hidden': isManuallyClose
-  }), [tooltipType, finalPosition, isVisible, isManuallyClose]);
-  const panelStyle = {
-    top: `${coords.top}px`,
-    left: `${coords.left}px`,
-    opacity: isVisible ? 1 : 0,
-    ...(zIndex && {
-      zIndex
-    })
-  };
+  const panelClassName = useMemo(() => classNames({
+    'ncua-tooltip-panel': !disablePortal
+  }, 'ncua-tooltip__bg', `ncua-tooltip__bg--${tooltipType}`, `ncua-tooltip__bg--${finalPosition}`, {
+    'ncua-tooltip__bg--visible': effectiveVisible,
+    'ncua-tooltip__bg--force-hidden': isManuallyClose && !forceVisible
+  }), [tooltipType, finalPosition, effectiveVisible, isManuallyClose, forceVisible, disablePortal]);
+  const panelStyle = buildPanelStyle(disablePortal, coords, effectiveVisible, zIndex);
   const portalTarget = mounted ? resolvePortalTarget() : null;
   const panel = _jsxs("span", {
     ref: panelRef,
@@ -194,29 +225,11 @@ export const Tooltip = _ref => {
       "aria-label": "\uD234\uD301 \uB2EB\uAE30"
     })]
   });
-  return _jsxs(_Fragment, {
-    children: [_jsxs("span", {
-      ref: anchorRef,
-      className: tooltipClassName,
-      onMouseEnter: handleMouseEnter,
-      onMouseLeave: handleMouseLeave,
-      children: [iconStyle === 'help-circle' && (iconType === 'stroke' ? _jsx(HelpCircle, {
-        width: iconSize,
-        height: iconSize,
-        color: iconColor
-      }) : _jsx(HelpCircleFill, {
-        width: iconSize,
-        height: iconSize,
-        color: iconColor
-      })), iconStyle === 'alert-circle' && (iconType === 'stroke' ? _jsx(AlertCircle, {
-        width: iconSize,
-        height: iconSize,
-        color: iconColor
-      }) : _jsx(AlertCircleFill, {
-        width: iconSize,
-        height: iconSize,
-        color: iconColor
-      }))]
-    }), portalTarget && /*#__PURE__*/createPortal(panel, portalTarget)]
+  return _jsxs("span", {
+    ref: anchorRef,
+    className: tooltipClassName,
+    onMouseEnter: handleMouseEnter,
+    onMouseLeave: handleMouseLeave,
+    children: [renderIcon(iconStyle, iconType, iconSize, iconColor), disablePortal ? panel : portalTarget && /*#__PURE__*/createPortal(panel, portalTarget)]
   });
 };