@ncds/ui-admin 1.8.25-alpha.0 → 1.8.25-alpha.1

package/dist/esm/src/utils/portal-position/__tests__/portalPosition.tracking.test.js

@@ -0,0 +1,394 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { applyPortalPanelStyle, buildPortalPanelStyle, observeAnchorGeometry, trackPortalPosition } from '..';
+const installResizeObserverStub = () => {
+  const instances = [];
+  class ResizeObserverStub {
+    constructor(_callback) {
+      this.observe = vi.fn();
+      this.unobserve = vi.fn();
+      this.disconnect = vi.fn();
+      instances.push(this);
+    }
+  }
+  vi.stubGlobal('ResizeObserver', ResizeObserverStub);
+  return {
+    instances
+  };
+};
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+const makeAnchorRect = function () {
+  let overrides = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  return {
+    top: 100,
+    bottom: 140,
+    left: 50,
+    right: 250,
+    width: 200,
+    ...overrides
+  };
+};
+const PANEL_HEIGHT = 300;
+const PANEL_WIDTH = 180;
+const DEFAULT_OFFSET = 4;
+const EXPECTED_Z_INDEX = 1500;
+const ON_CHANGE_CALLS = {
+  initial: 1,
+  afterScroll: 2,
+  afterResize: 3
+};
+const toDomRect = rect => DOMRect.fromRect({
+  x: rect.left,
+  y: rect.top,
+  width: rect.width,
+  height: rect.bottom - rect.top
+});
+const createAnchor = function () {
+  let rect = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : makeAnchorRect();
+  const element = document.createElement('button');
+  document.body.appendChild(element);
+  const boundingRect = vi.spyOn(element, 'getBoundingClientRect').mockReturnValue(toDomRect(rect));
+  const moveTo = next => boundingRect.mockReturnValue(toDomRect(next));
+  return {
+    element,
+    moveTo
+  };
+};
+const createPanel = function () {
+  let {
+    height,
+    width
+  } = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {
+    height: PANEL_HEIGHT,
+    width: PANEL_WIDTH
+  };
+  const element = document.createElement('div');
+  document.body.appendChild(element);
+  Object.defineProperty(element, 'offsetHeight', {
+    value: height,
+    configurable: true
+  });
+  Object.defineProperty(element, 'offsetWidth', {
+    value: width,
+    configurable: true
+  });
+  return element;
+};
+const dispatchWindow = type => window.dispatchEvent(new Event(type));
+describe('observeAnchorGeometry — 구독 (E-6)', () => {
+  it('구독 직후 onChange 를 1회 호출하고 window scroll·resize 마다 다시 호출한다', () => {
+    installResizeObserverStub();
+    const anchor = createAnchor();
+    const onChange = vi.fn();
+    const cleanup = observeAnchorGeometry({
+      getAnchor: () => anchor.element,
+      getPanel: () => null,
+      onChange
+    });
+    expect(onChange).toHaveBeenCalledTimes(ON_CHANGE_CALLS.initial);
+    dispatchWindow('scroll');
+    expect(onChange).toHaveBeenCalledTimes(ON_CHANGE_CALLS.afterScroll);
+    dispatchWindow('resize');
+    expect(onChange).toHaveBeenCalledTimes(ON_CHANGE_CALLS.afterResize);
+    cleanup();
+  });
+  it('중첩 컨테이너의 scroll(비버블링) 도 capture 로 포착한다', () => {
+    installResizeObserverStub();
+    const anchor = createAnchor();
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    const onChange = vi.fn();
+    const cleanup = observeAnchorGeometry({
+      getAnchor: () => anchor.element,
+      getPanel: () => null,
+      onChange
+    });
+    container.dispatchEvent(new Event('scroll', {
+      bubbles: false
+    }));
+    expect(onChange).toHaveBeenCalledTimes(ON_CHANGE_CALLS.afterScroll);
+    cleanup();
+  });
+  it('anchor 와 panel 각각에 ResizeObserver 를 붙인다', () => {
+    const {
+      instances
+    } = installResizeObserverStub();
+    const anchor = createAnchor();
+    const panel = createPanel();
+    const cleanup = observeAnchorGeometry({
+      getAnchor: () => anchor.element,
+      getPanel: () => panel,
+      onChange: vi.fn()
+    });
+    expect(instances).toHaveLength(2);
+    expect(instances[0]?.observe).toHaveBeenCalledWith(anchor.element);
+    expect(instances[1]?.observe).toHaveBeenCalledWith(panel);
+    cleanup();
+  });
+  it('구독 시점에 panel 이 없으면 anchor 옵저버만 만든다', () => {
+    const {
+      instances
+    } = installResizeObserverStub();
+    const anchor = createAnchor();
+    const cleanup = observeAnchorGeometry({
+      getAnchor: () => anchor.element,
+      getPanel: () => null,
+      onChange: vi.fn()
+    });
+    expect(instances).toHaveLength(1);
+    cleanup();
+  });
+  it('anchor 가 null 이면 구독하지 않고 no-op cleanup 을 반환한다', () => {
+    const {
+      instances
+    } = installResizeObserverStub();
+    const addEventListener = vi.spyOn(window, 'addEventListener');
+    const onChange = vi.fn();
+    const cleanup = observeAnchorGeometry({
+      getAnchor: () => null,
+      getPanel: () => null,
+      onChange
+    });
+    expect(onChange).not.toHaveBeenCalled();
+    expect(addEventListener).not.toHaveBeenCalled();
+    expect(instances).toHaveLength(0);
+    expect(() => cleanup()).not.toThrow();
+  });
+});
+describe('observeAnchorGeometry — cleanup (E-7)', () => {
+  it('cleanup 뒤에는 이벤트가 발생해도 onChange 가 늘지 않고 옵저버가 disconnect 된다', () => {
+    const {
+      instances
+    } = installResizeObserverStub();
+    const anchor = createAnchor();
+    const panel = createPanel();
+    const onChange = vi.fn();
+    const cleanup = observeAnchorGeometry({
+      getAnchor: () => anchor.element,
+      getPanel: () => panel,
+      onChange
+    });
+    cleanup();
+    dispatchWindow('scroll');
+    dispatchWindow('resize');
+    expect(onChange).toHaveBeenCalledTimes(ON_CHANGE_CALLS.initial);
+    for (const instance of instances) {
+      expect(instance.disconnect).toHaveBeenCalledTimes(1);
+    }
+  });
+});
+describe('observeAnchorGeometry — ResizeObserver 미정의 환경 (E-8)', () => {
+  it('ResizeObserver 가 없어도 예외 없이 window 이벤트만 구독한다', () => {
+    expect('ResizeObserver' in globalThis).toBe(false);
+    const anchor = createAnchor();
+    const onChange = vi.fn();
+    let cleanup = () => undefined;
+    expect(() => {
+      cleanup = observeAnchorGeometry({
+        getAnchor: () => anchor.element,
+        getPanel: () => null,
+        onChange
+      });
+    }).not.toThrow();
+    dispatchWindow('scroll');
+    expect(onChange).toHaveBeenCalledTimes(ON_CHANGE_CALLS.afterScroll);
+    cleanup();
+  });
+});
+describe('trackPortalPosition — 측정·조립 합성', () => {
+  it('구독 직후 anchor·panel 실측값으로 조립한 style 을 onUpdate 에 동기 전달한다', () => {
+    installResizeObserverStub();
+    const rect = makeAnchorRect();
+    const anchor = createAnchor(rect);
+    const panel = createPanel();
+    const onUpdate = vi.fn();
+    const cleanup = trackPortalPosition({
+      getAnchor: () => anchor.element,
+      getPanel: () => panel,
+      direction: 'down',
+      align: 'right',
+      onUpdate
+    });
+    expect(onUpdate).toHaveBeenCalledTimes(1);
+    expect(onUpdate).toHaveBeenLastCalledWith(buildPortalPanelStyle({
+      anchorRect: rect,
+      panelHeight: PANEL_HEIGHT,
+      panelWidth: PANEL_WIDTH,
+      direction: 'down',
+      align: 'right'
+    }));
+    cleanup();
+  });
+  it('panel 이 아직 없으면 panelHeight 0 · panelWidth 는 anchor 너비로 조립한다', () => {
+    installResizeObserverStub();
+    const rect = makeAnchorRect();
+    const anchor = createAnchor(rect);
+    const onUpdate = vi.fn();
+    const cleanup = trackPortalPosition({
+      getAnchor: () => anchor.element,
+      getPanel: () => null,
+      direction: 'up',
+      align: 'right',
+      onUpdate
+    });
+    expect(onUpdate).toHaveBeenLastCalledWith({
+      position: 'fixed',
+      top: rect.top - DEFAULT_OFFSET,
+      left: rect.right - rect.width,
+      zIndex: EXPECTED_Z_INDEX
+    });
+    cleanup();
+  });
+  it('matchAnchorWidth=true 이면 minWidth 를 anchor 너비로 낸다', () => {
+    installResizeObserverStub();
+    const rect = makeAnchorRect();
+    const anchor = createAnchor(rect);
+    const panel = createPanel();
+    const onUpdate = vi.fn();
+    const cleanup = trackPortalPosition({
+      getAnchor: () => anchor.element,
+      getPanel: () => panel,
+      direction: 'down',
+      matchAnchorWidth: true,
+      onUpdate
+    });
+    expect(onUpdate.mock.lastCall?.[0].minWidth).toBe(rect.width);
+    cleanup();
+  });
+  it('scroll 이 발생하면 anchor 를 다시 측정해 갱신된 style 을 전달한다', () => {
+    installResizeObserverStub();
+    const anchor = createAnchor(makeAnchorRect());
+    const panel = createPanel();
+    const movedRect = makeAnchorRect({
+      top: 60,
+      bottom: 100
+    });
+    const onUpdate = vi.fn();
+    const cleanup = trackPortalPosition({
+      getAnchor: () => anchor.element,
+      getPanel: () => panel,
+      direction: 'down',
+      onUpdate
+    });
+    anchor.moveTo(movedRect);
+    dispatchWindow('scroll');
+    expect(onUpdate).toHaveBeenCalledTimes(2);
+    expect(onUpdate.mock.lastCall?.[0].top).toBe(movedRect.bottom + DEFAULT_OFFSET);
+    cleanup();
+  });
+  it('getPanel 이 나중에 요소를 반환하면 다음 갱신에 panelHeight 가 반영된다', () => {
+    installResizeObserverStub();
+    const rect = makeAnchorRect();
+    const anchor = createAnchor(rect);
+    const panel = createPanel();
+    const mounted = {
+      current: null
+    };
+    const onUpdate = vi.fn();
+    const cleanup = trackPortalPosition({
+      getAnchor: () => anchor.element,
+      getPanel: () => mounted.current,
+      direction: 'up',
+      onUpdate
+    });
+    expect(onUpdate.mock.lastCall?.[0].top).toBe(rect.top - DEFAULT_OFFSET);
+    mounted.current = panel;
+    dispatchWindow('scroll');
+    expect(onUpdate.mock.lastCall?.[0].top).toBe(rect.top - PANEL_HEIGHT - DEFAULT_OFFSET);
+    cleanup();
+  });
+  it('anchor 가 null 이면 onUpdate 를 호출하지 않고 리스너도 붙이지 않는다', () => {
+    installResizeObserverStub();
+    const addEventListener = vi.spyOn(window, 'addEventListener');
+    const onUpdate = vi.fn();
+    const cleanup = trackPortalPosition({
+      getAnchor: () => null,
+      getPanel: () => null,
+      direction: 'down',
+      onUpdate
+    });
+    expect(onUpdate).not.toHaveBeenCalled();
+    expect(addEventListener).not.toHaveBeenCalled();
+    expect(() => cleanup()).not.toThrow();
+  });
+  it('cleanup 뒤에는 scroll 이 발생해도 onUpdate 가 늘지 않는다', () => {
+    installResizeObserverStub();
+    const anchor = createAnchor();
+    const onUpdate = vi.fn();
+    const cleanup = trackPortalPosition({
+      getAnchor: () => anchor.element,
+      getPanel: () => null,
+      direction: 'down',
+      onUpdate
+    });
+    cleanup();
+    dispatchWindow('scroll');
+    expect(onUpdate).toHaveBeenCalledTimes(1);
+  });
+});
+describe('trackPortalPosition — direction 게터 (추가형 API)', () => {
+  it('direction 에 함수를 넘기면 갱신마다 그 반환값으로 조립한다', () => {
+    installResizeObserverStub();
+    const anchor = createAnchor();
+    const panel = createPanel();
+    const onUpdate = vi.fn();
+    let direction = 'down';
+    trackPortalPosition({
+      getAnchor: () => anchor.element,
+      getPanel: () => panel,
+      direction: () => direction,
+      onUpdate
+    });
+    direction = 'up';
+    dispatchWindow('scroll');
+    expect(onUpdate.mock.calls[0][0].top).toBe(makeAnchorRect().bottom + DEFAULT_OFFSET);
+    expect(onUpdate.mock.calls[1][0].top).toBe(makeAnchorRect().top - PANEL_HEIGHT - DEFAULT_OFFSET);
+  });
+});
+describe('applyPortalPanelStyle — vanilla 어댑터 보조', () => {
+  it('position·top·left·zIndex 를 px 단위로 element.style 에 적용한다', () => {
+    const element = document.createElement('div');
+    applyPortalPanelStyle(element, {
+      position: 'fixed',
+      top: 144,
+      left: 50,
+      zIndex: EXPECTED_Z_INDEX
+    });
+    expect(element.style.position).toBe('fixed');
+    expect(element.style.top).toBe('144px');
+    expect(element.style.left).toBe('50px');
+    expect(element.style.zIndex).toBe('1500');
+    expect(element.style.minWidth).toBe('');
+  });
+  it('minWidth 가 있으면 px 단위로 함께 적용한다', () => {
+    const element = document.createElement('div');
+    applyPortalPanelStyle(element, {
+      position: 'fixed',
+      top: 144,
+      left: 50,
+      zIndex: EXPECTED_Z_INDEX,
+      minWidth: 200
+    });
+    expect(element.style.minWidth).toBe('200px');
+  });
+  it('이전 호출에서 minWidth 가 설정된 요소에 minWidth 없는 스타일을 적용하면 minWidth 를 제거한다', () => {
+    const element = document.createElement('div');
+    applyPortalPanelStyle(element, {
+      position: 'fixed',
+      top: 0,
+      left: 0,
+      zIndex: EXPECTED_Z_INDEX,
+      minWidth: 200
+    });
+    applyPortalPanelStyle(element, {
+      position: 'fixed',
+      top: 10,
+      left: 0,
+      zIndex: EXPECTED_Z_INDEX
+    });
+    expect(element.style.minWidth).toBe('');
+  });
+});

package/dist/esm/src/utils/portal-position/index.js

@@ -0,0 +1 @@
+export * from './portalPosition';

package/dist/esm/src/utils/portal-position/portalPosition.js

@@ -0,0 +1,150 @@
+const DEFAULT_OFFSET = 4;
+const DEFAULT_GAP = 20;
+const noop = () => undefined;
+const observeElementResize = (target, onChange) => {
+  if (target === null || typeof ResizeObserver === 'undefined') {
+    return null;
+  }
+  const observer = new ResizeObserver(onChange);
+  observer.observe(target);
+  return observer;
+};
+const measurePortalPanelStyle = _ref => {
+  let {
+    getAnchor,
+    getPanel,
+    direction,
+    align,
+    offset,
+    matchAnchorWidth
+  } = _ref;
+  const anchor = getAnchor();
+  if (anchor === null) {
+    return null;
+  }
+  const panel = getPanel();
+  return buildPortalPanelStyle({
+    anchorRect: anchor.getBoundingClientRect(),
+    panelHeight: panel?.offsetHeight ?? 0,
+    // matchAnchorWidth 이면 패널 너비를 쓰지 않으므로 offsetWidth 를 읽지 않는다 — 레이아웃 강제 산출 1회 회피
+    panelWidth: matchAnchorWidth ? null : panel?.offsetWidth ?? null,
+    direction: typeof direction === 'function' ? direction() : direction,
+    align,
+    offset,
+    matchAnchorWidth
+  });
+};
+export const PORTAL_PANEL_Z_INDEX = 1500;
+export const computePortalPosition = _ref2 => {
+  let {
+    anchorRect,
+    panelHeight,
+    panelWidth,
+    direction,
+    align = 'left',
+    offset = DEFAULT_OFFSET
+  } = _ref2;
+  return {
+    top: direction === 'up' ? anchorRect.top - panelHeight - offset : anchorRect.bottom + offset,
+    left: align === 'right' ? anchorRect.right - panelWidth : anchorRect.left
+  };
+};
+export const resolveDropdownDirection = _ref3 => {
+  let {
+    anchorRect,
+    panelHeight,
+    viewportHeight,
+    gap = DEFAULT_GAP
+  } = _ref3;
+  return viewportHeight - anchorRect.bottom < panelHeight + gap ? 'up' : 'down';
+};
+export const buildPortalPanelStyle = _ref4 => {
+  let {
+    anchorRect,
+    panelHeight,
+    panelWidth,
+    direction,
+    align,
+    offset,
+    matchAnchorWidth = false
+  } = _ref4;
+  const effectivePanelWidth = matchAnchorWidth || panelWidth === null ? anchorRect.width : panelWidth;
+  const {
+    top,
+    left
+  } = computePortalPosition({
+    anchorRect,
+    panelHeight,
+    panelWidth: effectivePanelWidth,
+    direction,
+    align,
+    offset
+  });
+  const base = {
+    position: 'fixed',
+    top,
+    left,
+    zIndex: PORTAL_PANEL_Z_INDEX
+  };
+  // width 가 아니라 min-width 인 이유: 패널은 max-content 로 자연 확장하되 앵커보다 좁아지지만 않게 한다.
+  // 옵션이 짧으면 앵커 너비, 길면 자연 확장 — Portal 이전 absolute 모드와 동일한 UX.
+  return matchAnchorWidth ? {
+    ...base,
+    minWidth: anchorRect.width
+  } : base;
+};
+export const observeAnchorGeometry = _ref5 => {
+  let {
+    getAnchor,
+    getPanel,
+    onChange
+  } = _ref5;
+  const anchor = getAnchor();
+  if (anchor === null) {
+    return noop;
+  }
+  onChange();
+  window.addEventListener('scroll', onChange, {
+    passive: true,
+    capture: true
+  });
+  window.addEventListener('resize', onChange);
+  const observers = [observeElementResize(anchor, onChange), observeElementResize(getPanel(), onChange)];
+  return () => {
+    window.removeEventListener('scroll', onChange, {
+      capture: true
+    });
+    window.removeEventListener('resize', onChange);
+    for (const observer of observers) {
+      observer?.disconnect();
+    }
+  };
+};
+export const trackPortalPosition = _ref6 => {
+  let {
+    onUpdate,
+    ...measureOptions
+  } = _ref6;
+  return observeAnchorGeometry({
+    getAnchor: measureOptions.getAnchor,
+    getPanel: measureOptions.getPanel,
+    onChange: () => {
+      const style = measurePortalPanelStyle(measureOptions);
+      if (style !== null) {
+        onUpdate(style);
+      }
+    }
+  });
+};
+// TODO(#497): vanilla 어댑터 도입 시 소비
+export const applyPortalPanelStyle = (element, style) => {
+  element.style.position = style.position;
+  element.style.top = `${style.top}px`;
+  element.style.left = `${style.left}px`;
+  element.style.zIndex = String(style.zIndex);
+  if (style.minWidth === undefined) {
+    element.style.removeProperty('min-width');
+    return;
+  }
+  element.style.minWidth = `${style.minWidth}px`;
+};

package/dist/temp/assets/scripts/notification/const/sizes.d.ts

@@ -28,5 +28,5 @@ export declare const getSizes: {
     readonly featuredIcon: (isMobile: boolean) => "sm" | "md";
     readonly iconPixel: (isMobile: boolean) => "20" | "16";
     readonly closeButton: (isMobile: boolean) => "xs" | "sm";
-    readonly closeButtonSvg: (size: keyof typeof CLOSE_BUTTON_SVG_SIZES) => 16 | 20;
+    readonly closeButtonSvg: (size: keyof typeof CLOSE_BUTTON_SVG_SIZES) => 20 | 16;
 };

package/dist/temp/src/components/action/button-group/ButtonGroup.d.ts

@@ -107,7 +107,7 @@ declare const ButtonGroup: {
         "aria-description"?: string | undefined;
         "aria-details"?: string | undefined;
         "aria-disabled"?: (boolean | "true" | "false") | undefined;
-        "aria-dropeffect"?: "link" | "none" | "copy" | "execute" | "move" | "popup" | undefined;
+        "aria-dropeffect"?: "copy" | "link" | "none" | "execute" | "move" | "popup" | undefined;
         "aria-errormessage"?: string | undefined;
         "aria-expanded"?: (boolean | "true" | "false") | undefined;
         "aria-flowto"?: string | undefined;

package/dist/temp/src/components/forms-and-input/combo-box/ComboBox.d.ts

@@ -34,6 +34,12 @@ interface ComboBoxProps extends Omit<ComponentPropsWithRef<'div'>, 'size' | 'onC
      * 완료 버튼 클릭 시 호출되는 콜백 — 현재 선택된 값을 인자로 받음 (multiple 모드에서만 트리거)
      */
     onComplete?: OptionChangeHandler;
+    /**
+     * 옵션 패널을 React Portal로 body에 렌더한다. 기본값 false — 명시적으로 켠 경우에만 동작한다.
+     * SelectBox·Dropdown 과 달리 FloatingContext.preferPortal 을 따르지 않는다. 컨텍스트를 따르면
+     * Table horizontalScroll 안의 기존 ComboBox 가 옵션 지정 없이 Portal 로 전환되기 때문이다.
+     */
+    usePortal?: boolean;
 }
 declare const ComboBox: import("react").ForwardRefExoticComponent<Omit<ComboBoxProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
 export { defaultMaxHeight, ComboBox };

package/dist/temp/src/components/forms-and-input/combo-box/ComboBox.js

@@ -1,8 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { ChevronSelectorVertical, SearchLg } from '@ncds/ui-admin-icon';
 import classNames from 'classnames';
-import { forwardRef, useImperativeHandle, useRef, useState } from 'react';
+import { forwardRef, useImperativeHandle, useRef, useState, } from 'react';
+import { createPortal } from 'react-dom';
 import { useDropdown } from '../../../hooks/dropdown';
+import { useFloatingPosition } from '../../../hooks/useFloatingPosition';
+import { usePortalState } from '../../../hooks/usePortalState';
 import { useMultiSelect } from '../../../utils/dropdown/multiSelect';
 import { Button } from '../../action/button';
 import { Tag } from '../../feedback-and-status/tag';
@@ -20,10 +23,38 @@ const notifyFormChange = (register, multiple, newValue) => {
         });
     }
 };
-const ComboBox = forwardRef(({ placeholder = '검색하세요', id, className, hintText, children, size = 'xs', destructive = false, value, optionItems = [], onChange, onSearch, disabled = false, register, maxHeight = defaultMaxHeight, searchValue = '', label, required = false, multiple = false, showFooterButtons = false, maxSelection, onEdit, onComplete, ...props }, ref) => {
+/**
+ * Portal 모드에서만 패널에 `--portal` 클래스와 fixed 좌표를 얹는다.
+ * floatingStyle 이 null 인 초기 레이아웃 직전에는 클래스만 붙지만,
+ * useLayoutEffect 가 paint 전에 좌표를 채우므로 빈 fixed 가 노출되지 않는다.
+ */
+const resolvePortalPanelBinding = (shouldPortal, floatingStyle) => {
+    if (!shouldPortal) {
+        return {};
+    }
+    return { className: 'ncua-select-dropdown--portal', style: floatingStyle ?? undefined };
+};
+/**
+ * 패널 노드를 인라인·Portal 두 마운트 지점 중 한 곳에만 넘긴다. 양쪽에 두면 dropdownRef 가
+ * 나중 노드로 덮여 외부 클릭 판정과 키보드 스크롤이 유령 노드를 가리키게 된다.
+ */
+const resolveDropdownMounts = ({ node, shouldPortal, portalContainer, isOpen, }) => {
+    if (!shouldPortal) {
+        return { inlineDropdown: node, portaledDropdown: null };
+    }
+    if (!portalContainer || !isOpen) {
+        return { inlineDropdown: null, portaledDropdown: null };
+    }
+    return { inlineDropdown: null, portaledDropdown: createPortal(node, portalContainer) };
+};
+const ComboBox = forwardRef(({ placeholder = '검색하세요', id, className, hintText, children, size = 'xs', destructive = false, value, optionItems = [], onChange, onSearch, disabled = false, register, maxHeight = defaultMaxHeight, searchValue = '', label, required = false, multiple = false, showFooterButtons = false, maxSelection, onEdit, onComplete, usePortal = false, ...props }, ref) => {
     const internalRef = useRef(null);
+    // 인라인 패널의 offset parent 가 __content 다. Portal 좌표도 같은 박스를 기준으로 잡아야
+    // label·hintText 가 있을 때 두 모드의 패널 위치가 어긋나지 않는다.
+    const contentRef = useRef(null);
     const dropdownRef = useRef(null);
     const inputRef = useRef(null);
+    const { shouldPortal, portalContainer } = usePortalState(usePortal);
     const [inputValue, setInputValue] = useState(searchValue);
     const [showAllItems, setShowAllItems] = useState(false);
     const [selectedTags, setSelectedTags] = useState([]);
@@ -65,6 +96,9 @@ const ComboBox = forwardRef(({ placeholder = '검색하세요', id, className, h
     const { isOpen, direction: dropdownDirection, focusedIndex, toggleDropdown, closeDropdown: dropdownClose, handleKeyDown: dropdownHandleKeyDown, handleOptionSelect: handleDropdownSelect, handleMouseMove, isKeyboardNavigation, } = useDropdown({
         triggerRef: internalRef,
         dropdownRef,
+        // Portal 모드에서는 hintText 등으로 root 가 content 보다 아래까지 차지할 수 있어
+        // internalRef 기준 direction 판정이 잘못될 수 있다. contentRef 로 교정한다.
+        positionRef: shouldPortal ? contentRef : undefined,
         maxHeight,
         itemCount: optionItems.length,
         optionItems: optionItems,
@@ -98,6 +132,14 @@ const ComboBox = forwardRef(({ placeholder = '검색하세요', id, className, h
         // 나머지는 useDropdown 훅에서 처리
         dropdownHandleKeyDown(e);
     };
+    const floatingStyle = useFloatingPosition({
+        enabled: shouldPortal,
+        isOpen,
+        triggerRef: contentRef,
+        floatingRef: dropdownRef,
+        direction: dropdownDirection,
+        matchTriggerWidth: true,
+    });
     // biome-ignore lint/style/noNonNullAssertion: forwardRef 패턴에서 internalRef는 첫 렌더 후 항상 존재
     useImperativeHandle(ref, () => internalRef.current, []);
     const trailingElement = {
@@ -150,14 +192,22 @@ const ComboBox = forwardRef(({ placeholder = '검색하세요', id, className, h
     const showFooter = multiple || showFooterButtons;
     const hiddenInputValue = multiple ? JSON.stringify(value || []) : String(value || '');
     const hasTags = selectedTags.length > 0;
+    const { className: portalPanelClassName, style: portalPanelStyle } = resolvePortalPanelBinding(shouldPortal, floatingStyle);
+    const selectDropdownNode = (_jsxs(SelectDropdown, { ref: dropdownRef, isOpen: isOpen, direction: dropdownDirection, size: size, options: displayedOptions, value: value, focusedIndex: focusedIndex, maxHeight: maxHeight, listboxId: comboboxId, onOptionSelect: handleDropdownSelect, onMouseMove: handleMouseMove, isKeyboardNavigation: isKeyboardNavigation, multiple: multiple, showFooterButtons: showFooter, selectAllButtonText: selectAllButtonText, showSelectAllAction: !isMaxSelectionActive, onSelectAll: handleSelectAll, onEdit: handleEdit, onComplete: handleComplete, componentType: "combobox", className: portalPanelClassName, style: portalPanelStyle, children: [showNoResults ? _jsx("li", { className: "ncua-select-dropdown__no-results", children: "\uC77C\uCE58\uD558\uB294 \uACB0\uACFC\uAC00 \uC5C6\uC2B5\uB2C8\uB2E4." }) : null, children] }));
+    const { inlineDropdown, portaledDropdown } = resolveDropdownMounts({
+        node: selectDropdownNode,
+        shouldPortal,
+        portalContainer,
+        isOpen,
+    });
     return (_jsxs(_Fragment, { children: [_jsxs("div", { ref: internalRef, className: classNames('ncua-combobox', `ncua-combobox--${size}`, {
                     'ncua-combobox--open': isOpen,
                     'ncua-combobox--disabled': disabled,
                     destructive: destructive,
-                }, className), ...props, children: [_jsxs("div", { className: "ncua-combobox__content", children: [_jsx(InputBase, { ref: inputRef, size: size, label: label, required: required, placeholder: placeholder, value: inputValue, onChange: handleInputChange, onKeyDown: handleKeyDown, onClick: handleInputClick, disabled: disabled, destructive: destructive, leadingElement: leadingElement, trailingElement: trailingElement, role: "combobox", "aria-expanded": isOpen, "aria-haspopup": "listbox", "aria-controls": comboboxId, "aria-disabled": disabled, autoComplete: "off", clearText: !!inputValue, onClearText: () => {
+                }, className), ...props, children: [_jsxs("div", { ref: contentRef, className: "ncua-combobox__content", children: [_jsx(InputBase, { ref: inputRef, size: size, label: label, required: required, placeholder: placeholder, value: inputValue, onChange: handleInputChange, onKeyDown: handleKeyDown, onClick: handleInputClick, disabled: disabled, destructive: destructive, leadingElement: leadingElement, trailingElement: trailingElement, role: "combobox", "aria-expanded": isOpen, "aria-haspopup": "listbox", "aria-controls": comboboxId, "aria-disabled": disabled, autoComplete: "off", clearText: !!inputValue, onClearText: () => {
                                     setInputValue('');
                                     onSearch?.('');
-                                } }), _jsxs(SelectDropdown, { ref: dropdownRef, isOpen: isOpen, direction: dropdownDirection, size: size, options: displayedOptions, value: value, focusedIndex: focusedIndex, maxHeight: maxHeight, listboxId: comboboxId, onOptionSelect: handleDropdownSelect, onMouseMove: handleMouseMove, isKeyboardNavigation: isKeyboardNavigation, multiple: multiple, showFooterButtons: showFooter, selectAllButtonText: selectAllButtonText, showSelectAllAction: !isMaxSelectionActive, onSelectAll: handleSelectAll, onEdit: handleEdit, onComplete: handleComplete, componentType: "combobox", children: [showNoResults ? _jsx("li", { className: "ncua-select-dropdown__no-results", children: "\uC77C\uCE58\uD558\uB294 \uACB0\uACFC\uAC00 \uC5C6\uC2B5\uB2C8\uB2E4." }) : null, children] })] }), register && _jsx("input", { type: "hidden", ...register, value: hiddenInputValue }), hintText && _jsx(HintText, { destructive: destructive, children: hintText })] }), hasTags && (_jsx("div", { className: "ncua-combobox__tags", children: selectedTags.map((tag) => (_jsx(Tag, { text: tag.label, size: "sm", close: true, onButtonClick: () => handleRemoveTag(tag.id) }, tag.id))) }))] }));
+                                } }), inlineDropdown, portaledDropdown] }), register && _jsx("input", { type: "hidden", ...register, value: hiddenInputValue }), hintText && _jsx(HintText, { destructive: destructive, children: hintText })] }), hasTags && (_jsx("div", { className: "ncua-combobox__tags", children: selectedTags.map((tag) => (_jsx(Tag, { text: tag.label, size: "sm", close: true, onButtonClick: () => handleRemoveTag(tag.id) }, tag.id))) }))] }));
 });
 ComboBox.displayName = 'ComboBox';
 export { defaultMaxHeight, ComboBox };

package/dist/temp/src/components/forms-and-input/combo-box/__tests__/ComboBox.portal.test.d.ts

@@ -0,0 +1 @@
+export {};