@ncds/ui-admin 1.8.25-alpha.2 → 1.8.25-alpha.3

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

@@ -8,7 +8,6 @@ var _jsxRuntime = require("react/jsx-runtime");
 var _uiAdminIcon = require("@ncds/ui-admin-icon");
 var _classnames = _interopRequireDefault(require("classnames"));
 var _react = require("react");
-var _reactDom = require("react-dom");
 var _dropdown = require("../../../hooks/dropdown");
 var _useFloatingPosition = require("../../../hooks/useFloatingPosition");
 var _usePortalState = require("../../../hooks/usePortalState");
@@ -18,6 +17,7 @@ var _tag = require("../../feedback-and-status/tag");
 var _selectDropdown = require("../../select-dropdown");
 var _HintText = require("../../shared/hintText/HintText");
 var _InputBase = require("../input-base/InputBase");
+var _utils = require("./utils");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 const defaultMaxHeight = exports.defaultMaxHeight = 275;
 const notifyFormChange = (register, multiple, newValue) => {
@@ -30,49 +30,7 @@ const notifyFormChange = (register, multiple, newValue) => {
     });
   }
 };
-/**
- * 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 = _ref => {
-  let {
-    node,
-    shouldPortal,
-    portalContainer,
-    isOpen
-  } = _ref;
-  if (!shouldPortal) {
-    return {
-      inlineDropdown: node,
-      portaledDropdown: null
-    };
-  }
-  if (!portalContainer || !isOpen) {
-    return {
-      inlineDropdown: null,
-      portaledDropdown: null
-    };
-  }
-  return {
-    inlineDropdown: null,
-    portaledDropdown: /*#__PURE__*/(0, _reactDom.createPortal)(node, portalContainer)
-  };
-};
-const ComboBox = exports.ComboBox = /*#__PURE__*/(0, _react.forwardRef)((_ref2, ref) => {
+const ComboBox = exports.ComboBox = /*#__PURE__*/(0, _react.forwardRef)((_ref, ref) => {
   let {
     placeholder = '검색하세요',
     id,
@@ -98,7 +56,7 @@ const ComboBox = exports.ComboBox = /*#__PURE__*/(0, _react.forwardRef)((_ref2,
     onComplete,
     usePortal = false,
     ...props
-  } = _ref2;
+  } = _ref;
   const internalRef = (0, _react.useRef)(null);
   // 인라인 패널의 offset parent 가 __content 다. Portal 좌표도 같은 박스를 기준으로 잡아야
   // label·hintText 가 있을 때 두 모드의 패널 위치가 어긋나지 않는다.
@@ -277,7 +235,7 @@ const ComboBox = exports.ComboBox = /*#__PURE__*/(0, _react.forwardRef)((_ref2,
   const {
     className: portalPanelClassName,
     style: portalPanelStyle
-  } = resolvePortalPanelBinding(shouldPortal, floatingStyle);
+  } = (0, _utils.resolvePortalPanelBinding)(shouldPortal, floatingStyle);
   const selectDropdownNode = (0, _jsxRuntime.jsxs)(_selectDropdown.SelectDropdown, {
     ref: dropdownRef,
     isOpen: isOpen,
@@ -309,7 +267,7 @@ const ComboBox = exports.ComboBox = /*#__PURE__*/(0, _react.forwardRef)((_ref2,
   const {
     inlineDropdown,
     portaledDropdown
-  } = resolveDropdownMounts({
+  } = (0, _utils.resolveDropdownMounts)({
     node: selectDropdownNode,
     shouldPortal,
     portalContainer,

package/dist/cjs/src/components/forms-and-input/combo-box/utils.js

@@ -0,0 +1,51 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.resolvePortalPanelBinding = exports.resolveDropdownMounts = void 0;
+var _reactDom = require("react-dom");
+/**
+ * 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 가
+ * 나중 노드로 덮여 외부 클릭 판정과 키보드 스크롤이 유령 노드를 가리키게 된다.
+ */
+exports.resolvePortalPanelBinding = resolvePortalPanelBinding;
+const resolveDropdownMounts = _ref => {
+  let {
+    node,
+    shouldPortal,
+    portalContainer,
+    isOpen
+  } = _ref;
+  if (!shouldPortal) {
+    return {
+      inlineDropdown: node,
+      portaledDropdown: null
+    };
+  }
+  if (!portalContainer || !isOpen) {
+    return {
+      inlineDropdown: null,
+      portaledDropdown: null
+    };
+  }
+  return {
+    inlineDropdown: null,
+    portaledDropdown: /*#__PURE__*/(0, _reactDom.createPortal)(node, portalContainer)
+  };
+};
+exports.resolveDropdownMounts = resolveDropdownMounts;

package/dist/cjs/src/hooks/__tests__/useFloatingPosition.test.js

@@ -319,4 +319,36 @@ const dispatchScroll = () => {
     });
     hook.unmount();
   });
+});
+(0, _vitest.describe)('useFloatingPosition — 좌표 불변 갱신', () => {
+  (0, _vitest.it)('scroll 뒤에도 top·left·minWidth 가 같으면 이전 style 참조를 유지해 하위 트리 리렌더를 건너뛴다', () => {
+    installResizeObserverStub();
+    const hook = renderHook(baseParams({
+      triggerRef: makeRef(createAnchor()),
+      floatingRef: makeRef(createPanel()),
+      matchTriggerWidth: true
+    }));
+    const styleBeforeScroll = hook.latest();
+    dispatchScroll();
+    (0, _vitest.expect)(hook.latest()).toBe(styleBeforeScroll);
+    hook.unmount();
+  });
+  (0, _vitest.it)('scroll 로 좌표가 바뀌면 새 style 로 다시 렌더링한다', () => {
+    installResizeObserverStub();
+    const anchor = createAnchor();
+    const hook = renderHook(baseParams({
+      triggerRef: makeRef(anchor),
+      floatingRef: makeRef(createPanel())
+    }));
+    const moved = makeAnchorRect({
+      top: 300,
+      bottom: 340
+    });
+    _vitest.vi.spyOn(anchor, 'getBoundingClientRect').mockReturnValue(toDomRect(moved));
+    dispatchScroll();
+    (0, _vitest.expect)(hook.latest()).toMatchObject({
+      top: moved.bottom + DEFAULT_OFFSET
+    });
+    hook.unmount();
+  });
 });

package/dist/cjs/src/hooks/useFloatingPosition.js

@@ -7,6 +7,7 @@ exports.useFloatingPosition = void 0;
 var _react = require("react");
 var _portalPosition = require("../utils/portal-position");
 var _useIsomorphicLayoutEffect = require("./useIsomorphicLayoutEffect");
+const isSamePlacement = (prev, next) => prev !== null && prev.top === next.top && prev.left === next.left && prev.minWidth === next.minWidth;
 const useFloatingPosition = _ref => {
   let {
     enabled,
@@ -31,7 +32,7 @@ const useFloatingPosition = _ref => {
       align,
       offset,
       matchAnchorWidth: matchTriggerWidth,
-      onUpdate: setStyle
+      onUpdate: next => setStyle(prev => isSamePlacement(prev, next) ? prev : next)
     });
   }, [enabled, isOpen, direction, offset, align, matchTriggerWidth, triggerRef, floatingRef]);
   return style;

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

@@ -115,6 +115,27 @@ const dispatchWindow = type => window.dispatchEvent(new Event(type));
     (0, _vitest.expect)(onChange).toHaveBeenCalledTimes(ON_CHANGE_CALLS.afterScroll);
     cleanup();
   });
+  (0, _vitest.it)('panel 자신과 그 내부 요소의 scroll 은 anchor 를 움직이지 않으므로 onChange 를 호출하지 않는다', () => {
+    installResizeObserverStub();
+    const anchor = createAnchor();
+    const panel = createPanel();
+    const optionList = document.createElement('ul');
+    panel.appendChild(optionList);
+    const onChange = _vitest.vi.fn();
+    const cleanup = (0, _.observeAnchorGeometry)({
+      getAnchor: () => anchor.element,
+      getPanel: () => panel,
+      onChange
+    });
+    panel.dispatchEvent(new Event('scroll', {
+      bubbles: false
+    }));
+    optionList.dispatchEvent(new Event('scroll', {
+      bubbles: false
+    }));
+    (0, _vitest.expect)(onChange).toHaveBeenCalledTimes(ON_CHANGE_CALLS.initial);
+    cleanup();
+  });
   (0, _vitest.it)('anchor 와 panel 각각에 ResizeObserver 를 붙인다', () => {
     const {
       instances

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

@@ -113,14 +113,19 @@ const observeAnchorGeometry = _ref5 => {
     return noop;
   }
   onChange();
-  window.addEventListener('scroll', onChange, {
+  // 패널 내부 스크롤은 anchor 를 움직이지 않는다
+  const onScroll = event => {
+    if (event.target instanceof Node && getPanel()?.contains(event.target)) return;
+    onChange();
+  };
+  window.addEventListener('scroll', onScroll, {
     passive: true,
     capture: true
   });
   window.addEventListener('resize', onChange);
   const observers = [observeElementResize(anchor, onChange), observeElementResize(getPanel(), onChange)];
   return () => {
-    window.removeEventListener('scroll', onChange, {
+    window.removeEventListener('scroll', onScroll, {
       capture: true
     });
     window.removeEventListener('resize', onChange);
@@ -146,7 +151,6 @@ const trackPortalPosition = _ref6 => {
     }
   });
 };
-// TODO(#497): vanilla 어댑터 도입 시 소비
 exports.trackPortalPosition = trackPortalPosition;
 const applyPortalPanelStyle = (element, style) => {
   element.style.position = style.position;

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

@@ -2,7 +2,6 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 import { ChevronSelectorVertical, SearchLg } from '@ncds/ui-admin-icon';
 import classNames from 'classnames';
 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';
@@ -12,6 +11,7 @@ import { Tag } from '../../feedback-and-status/tag';
 import { SelectDropdown } from '../../select-dropdown';
 import { HintText } from '../../shared/hintText/HintText';
 import { InputBase } from '../input-base/InputBase';
+import { resolveDropdownMounts, resolvePortalPanelBinding } from './utils';
 const defaultMaxHeight = 275;
 const notifyFormChange = (register, multiple, newValue) => {
   if (register?.onChange) {
@@ -23,49 +23,7 @@ const notifyFormChange = (register, multiple, newValue) => {
     });
   }
 };
-/**
- * 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 = _ref => {
-  let {
-    node,
-    shouldPortal,
-    portalContainer,
-    isOpen
-  } = _ref;
-  if (!shouldPortal) {
-    return {
-      inlineDropdown: node,
-      portaledDropdown: null
-    };
-  }
-  if (!portalContainer || !isOpen) {
-    return {
-      inlineDropdown: null,
-      portaledDropdown: null
-    };
-  }
-  return {
-    inlineDropdown: null,
-    portaledDropdown: /*#__PURE__*/createPortal(node, portalContainer)
-  };
-};
-const ComboBox = /*#__PURE__*/forwardRef((_ref2, ref) => {
+const ComboBox = /*#__PURE__*/forwardRef((_ref, ref) => {
   let {
     placeholder = '검색하세요',
     id,
@@ -91,7 +49,7 @@ const ComboBox = /*#__PURE__*/forwardRef((_ref2, ref) => {
     onComplete,
     usePortal = false,
     ...props
-  } = _ref2;
+  } = _ref;
   const internalRef = useRef(null);
   // 인라인 패널의 offset parent 가 __content 다. Portal 좌표도 같은 박스를 기준으로 잡아야
   // label·hintText 가 있을 때 두 모드의 패널 위치가 어긋나지 않는다.

package/dist/esm/src/components/forms-and-input/combo-box/utils.js

@@ -0,0 +1,43 @@
+import { createPortal } from 'react-dom';
+/**
+ * Portal 모드에서만 패널에 `--portal` 클래스와 fixed 좌표를 얹는다.
+ * floatingStyle 이 null 인 초기 레이아웃 직전에는 클래스만 붙지만,
+ * useLayoutEffect 가 paint 전에 좌표를 채우므로 빈 fixed 가 노출되지 않는다.
+ */
+export const resolvePortalPanelBinding = (shouldPortal, floatingStyle) => {
+  if (!shouldPortal) {
+    return {};
+  }
+  return {
+    className: 'ncua-select-dropdown--portal',
+    style: floatingStyle ?? undefined
+  };
+};
+/**
+ * 패널 노드를 인라인·Portal 두 마운트 지점 중 한 곳에만 넘긴다. 양쪽에 두면 dropdownRef 가
+ * 나중 노드로 덮여 외부 클릭 판정과 키보드 스크롤이 유령 노드를 가리키게 된다.
+ */
+export const resolveDropdownMounts = _ref => {
+  let {
+    node,
+    shouldPortal,
+    portalContainer,
+    isOpen
+  } = _ref;
+  if (!shouldPortal) {
+    return {
+      inlineDropdown: node,
+      portaledDropdown: null
+    };
+  }
+  if (!portalContainer || !isOpen) {
+    return {
+      inlineDropdown: null,
+      portaledDropdown: null
+    };
+  }
+  return {
+    inlineDropdown: null,
+    portaledDropdown: /*#__PURE__*/createPortal(node, portalContainer)
+  };
+};

package/dist/esm/src/hooks/__tests__/useFloatingPosition.test.js

@@ -316,4 +316,36 @@ describe('useFloatingPosition — 프롭 변경 재구독 (E-5)', () => {
     });
     hook.unmount();
   });
+});
+describe('useFloatingPosition — 좌표 불변 갱신', () => {
+  it('scroll 뒤에도 top·left·minWidth 가 같으면 이전 style 참조를 유지해 하위 트리 리렌더를 건너뛴다', () => {
+    installResizeObserverStub();
+    const hook = renderHook(baseParams({
+      triggerRef: makeRef(createAnchor()),
+      floatingRef: makeRef(createPanel()),
+      matchTriggerWidth: true
+    }));
+    const styleBeforeScroll = hook.latest();
+    dispatchScroll();
+    expect(hook.latest()).toBe(styleBeforeScroll);
+    hook.unmount();
+  });
+  it('scroll 로 좌표가 바뀌면 새 style 로 다시 렌더링한다', () => {
+    installResizeObserverStub();
+    const anchor = createAnchor();
+    const hook = renderHook(baseParams({
+      triggerRef: makeRef(anchor),
+      floatingRef: makeRef(createPanel())
+    }));
+    const moved = makeAnchorRect({
+      top: 300,
+      bottom: 340
+    });
+    vi.spyOn(anchor, 'getBoundingClientRect').mockReturnValue(toDomRect(moved));
+    dispatchScroll();
+    expect(hook.latest()).toMatchObject({
+      top: moved.bottom + DEFAULT_OFFSET
+    });
+    hook.unmount();
+  });
 });

package/dist/esm/src/hooks/useFloatingPosition.js

@@ -1,6 +1,7 @@
 import { useState } from 'react';
 import { trackPortalPosition } from '../utils/portal-position';
 import { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect';
+const isSamePlacement = (prev, next) => prev !== null && prev.top === next.top && prev.left === next.left && prev.minWidth === next.minWidth;
 export const useFloatingPosition = _ref => {
   let {
     enabled,
@@ -25,7 +26,7 @@ export const useFloatingPosition = _ref => {
       align,
       offset,
       matchAnchorWidth: matchTriggerWidth,
-      onUpdate: setStyle
+      onUpdate: next => setStyle(prev => isSamePlacement(prev, next) ? prev : next)
     });
   }, [enabled, isOpen, direction, offset, align, matchTriggerWidth, triggerRef, floatingRef]);
   return style;

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

@@ -112,6 +112,27 @@ describe('observeAnchorGeometry — 구독 (E-6)', () => {
     expect(onChange).toHaveBeenCalledTimes(ON_CHANGE_CALLS.afterScroll);
     cleanup();
   });
+  it('panel 자신과 그 내부 요소의 scroll 은 anchor 를 움직이지 않으므로 onChange 를 호출하지 않는다', () => {
+    installResizeObserverStub();
+    const anchor = createAnchor();
+    const panel = createPanel();
+    const optionList = document.createElement('ul');
+    panel.appendChild(optionList);
+    const onChange = vi.fn();
+    const cleanup = observeAnchorGeometry({
+      getAnchor: () => anchor.element,
+      getPanel: () => panel,
+      onChange
+    });
+    panel.dispatchEvent(new Event('scroll', {
+      bubbles: false
+    }));
+    optionList.dispatchEvent(new Event('scroll', {
+      bubbles: false
+    }));
+    expect(onChange).toHaveBeenCalledTimes(ON_CHANGE_CALLS.initial);
+    cleanup();
+  });
   it('anchor 와 panel 각각에 ResizeObserver 를 붙인다', () => {
     const {
       instances

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

@@ -104,14 +104,19 @@ export const observeAnchorGeometry = _ref5 => {
     return noop;
   }
   onChange();
-  window.addEventListener('scroll', onChange, {
+  // 패널 내부 스크롤은 anchor 를 움직이지 않는다
+  const onScroll = event => {
+    if (event.target instanceof Node && getPanel()?.contains(event.target)) return;
+    onChange();
+  };
+  window.addEventListener('scroll', onScroll, {
     passive: true,
     capture: true
   });
   window.addEventListener('resize', onChange);
   const observers = [observeElementResize(anchor, onChange), observeElementResize(getPanel(), onChange)];
   return () => {
-    window.removeEventListener('scroll', onChange, {
+    window.removeEventListener('scroll', onScroll, {
       capture: true
     });
     window.removeEventListener('resize', onChange);
@@ -136,7 +141,6 @@ export const trackPortalPosition = _ref6 => {
     }
   });
 };
-// TODO(#497): vanilla 어댑터 도입 시 소비
 export const applyPortalPanelStyle = (element, style) => {
   element.style.position = style.position;
   element.style.top = `${style.top}px`;

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

@@ -1,8 +1,7 @@
 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 { createPortal } from 'react-dom';
+import { forwardRef, useImperativeHandle, useRef, useState } from 'react';
 import { useDropdown } from '../../../hooks/dropdown';
 import { useFloatingPosition } from '../../../hooks/useFloatingPosition';
 import { usePortalState } from '../../../hooks/usePortalState';
@@ -12,6 +11,7 @@ import { Tag } from '../../feedback-and-status/tag';
 import { SelectDropdown } from '../../select-dropdown';
 import { HintText } from '../../shared/hintText/HintText';
 import { InputBase } from '../input-base/InputBase';
+import { resolveDropdownMounts, resolvePortalPanelBinding } from './utils';
 const defaultMaxHeight = 275;
 const notifyFormChange = (register, multiple, newValue) => {
     if (register?.onChange) {
@@ -23,30 +23,6 @@ const notifyFormChange = (register, multiple, newValue) => {
         });
     }
 };
-/**
- * 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 좌표도 같은 박스를 기준으로 잡아야

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

@@ -0,0 +1,27 @@
+import type { CSSProperties, ReactNode } from 'react';
+type PortalPanelBinding = {
+    className?: string;
+    style?: CSSProperties;
+};
+type DropdownMounts = {
+    inlineDropdown: ReactNode;
+    portaledDropdown: ReactNode;
+};
+type ResolveDropdownMountsParams = {
+    node: ReactNode;
+    shouldPortal: boolean;
+    portalContainer: HTMLElement | null;
+    isOpen: boolean;
+};
+/**
+ * Portal 모드에서만 패널에 `--portal` 클래스와 fixed 좌표를 얹는다.
+ * floatingStyle 이 null 인 초기 레이아웃 직전에는 클래스만 붙지만,
+ * useLayoutEffect 가 paint 전에 좌표를 채우므로 빈 fixed 가 노출되지 않는다.
+ */
+export declare const resolvePortalPanelBinding: (shouldPortal: boolean, floatingStyle: CSSProperties | null) => PortalPanelBinding;
+/**
+ * 패널 노드를 인라인·Portal 두 마운트 지점 중 한 곳에만 넘긴다. 양쪽에 두면 dropdownRef 가
+ * 나중 노드로 덮여 외부 클릭 판정과 키보드 스크롤이 유령 노드를 가리키게 된다.
+ */
+export declare const resolveDropdownMounts: ({ node, shouldPortal, portalContainer, isOpen, }: ResolveDropdownMountsParams) => DropdownMounts;
+export {};

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

@@ -0,0 +1,25 @@
+import { createPortal } from 'react-dom';
+/**
+ * Portal 모드에서만 패널에 `--portal` 클래스와 fixed 좌표를 얹는다.
+ * floatingStyle 이 null 인 초기 레이아웃 직전에는 클래스만 붙지만,
+ * useLayoutEffect 가 paint 전에 좌표를 채우므로 빈 fixed 가 노출되지 않는다.
+ */
+export const resolvePortalPanelBinding = (shouldPortal, floatingStyle) => {
+    if (!shouldPortal) {
+        return {};
+    }
+    return { className: 'ncua-select-dropdown--portal', style: floatingStyle ?? undefined };
+};
+/**
+ * 패널 노드를 인라인·Portal 두 마운트 지점 중 한 곳에만 넘긴다. 양쪽에 두면 dropdownRef 가
+ * 나중 노드로 덮여 외부 클릭 판정과 키보드 스크롤이 유령 노드를 가리키게 된다.
+ */
+export 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) };
+};

package/dist/temp/src/hooks/__tests__/useFloatingPosition.test.js

@@ -203,3 +203,27 @@ describe('useFloatingPosition — 프롭 변경 재구독 (E-5)', () => {
         hook.unmount();
     });
 });
+describe('useFloatingPosition — 좌표 불변 갱신', () => {
+    it('scroll 뒤에도 top·left·minWidth 가 같으면 이전 style 참조를 유지해 하위 트리 리렌더를 건너뛴다', () => {
+        installResizeObserverStub();
+        const hook = renderHook(baseParams({
+            triggerRef: makeRef(createAnchor()),
+            floatingRef: makeRef(createPanel()),
+            matchTriggerWidth: true,
+        }));
+        const styleBeforeScroll = hook.latest();
+        dispatchScroll();
+        expect(hook.latest()).toBe(styleBeforeScroll);
+        hook.unmount();
+    });
+    it('scroll 로 좌표가 바뀌면 새 style 로 다시 렌더링한다', () => {
+        installResizeObserverStub();
+        const anchor = createAnchor();
+        const hook = renderHook(baseParams({ triggerRef: makeRef(anchor), floatingRef: makeRef(createPanel()) }));
+        const moved = makeAnchorRect({ top: 300, bottom: 340 });
+        vi.spyOn(anchor, 'getBoundingClientRect').mockReturnValue(toDomRect(moved));
+        dispatchScroll();
+        expect(hook.latest()).toMatchObject({ top: moved.bottom + DEFAULT_OFFSET });
+        hook.unmount();
+    });
+});

package/dist/temp/src/hooks/useFloatingPosition.js

@@ -1,6 +1,7 @@
 import { useState } from 'react';
-import { trackPortalPosition } from '../utils/portal-position';
+import { trackPortalPosition, } from '../utils/portal-position';
 import { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect';
+const isSamePlacement = (prev, next) => prev !== null && prev.top === next.top && prev.left === next.left && prev.minWidth === next.minWidth;
 export const useFloatingPosition = ({ enabled, isOpen, triggerRef, floatingRef, direction, offset, align, matchTriggerWidth = false, }) => {
     const [style, setStyle] = useState(null);
     useIsomorphicLayoutEffect(() => {
@@ -15,7 +16,7 @@ export const useFloatingPosition = ({ enabled, isOpen, triggerRef, floatingRef,
             align,
             offset,
             matchAnchorWidth: matchTriggerWidth,
-            onUpdate: setStyle,
+            onUpdate: (next) => setStyle((prev) => (isSamePlacement(prev, next) ? prev : next)),
         });
     }, [enabled, isOpen, direction, offset, align, matchTriggerWidth, triggerRef, floatingRef]);
     return style;

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

@@ -71,6 +71,19 @@ describe('observeAnchorGeometry — 구독 (E-6)', () => {
         expect(onChange).toHaveBeenCalledTimes(ON_CHANGE_CALLS.afterScroll);
         cleanup();
     });
+    it('panel 자신과 그 내부 요소의 scroll 은 anchor 를 움직이지 않으므로 onChange 를 호출하지 않는다', () => {
+        installResizeObserverStub();
+        const anchor = createAnchor();
+        const panel = createPanel();
+        const optionList = document.createElement('ul');
+        panel.appendChild(optionList);
+        const onChange = vi.fn();
+        const cleanup = observeAnchorGeometry({ getAnchor: () => anchor.element, getPanel: () => panel, onChange });
+        panel.dispatchEvent(new Event('scroll', { bubbles: false }));
+        optionList.dispatchEvent(new Event('scroll', { bubbles: false }));
+        expect(onChange).toHaveBeenCalledTimes(ON_CHANGE_CALLS.initial);
+        cleanup();
+    });
     it('anchor 와 panel 각각에 ResizeObserver 를 붙인다', () => {
         const { instances } = installResizeObserverStub();
         const anchor = createAnchor();

package/dist/temp/src/utils/portal-position/portalPosition.d.ts

@@ -2,7 +2,7 @@ export type PortalDirection = 'up' | 'down';
 export type PortalAlign = 'left' | 'right';
 export type AnchorRect = Readonly<Pick<DOMRectReadOnly, 'top' | 'bottom' | 'left' | 'right' | 'width'>>;
 export declare const PORTAL_PANEL_Z_INDEX = 1500;
-export type ComputePortalPositionInput = Readonly<{
+export type ComputePortalPositionParams = Readonly<{
     anchorRect: AnchorRect;
     panelHeight: number;
     panelWidth: number;
@@ -14,15 +14,15 @@ export type PortalPosition = Readonly<{
     top: number;
     left: number;
 }>;
-export declare const computePortalPosition: ({ anchorRect, panelHeight, panelWidth, direction, align, offset, }: ComputePortalPositionInput) => PortalPosition;
-export type ResolveDropdownDirectionInput = Readonly<{
+export declare const computePortalPosition: ({ anchorRect, panelHeight, panelWidth, direction, align, offset, }: ComputePortalPositionParams) => PortalPosition;
+export type ResolveDropdownDirectionParams = Readonly<{
     anchorRect: Pick<AnchorRect, 'bottom'>;
     panelHeight: number;
     viewportHeight: number;
     gap?: number;
 }>;
-export declare const resolveDropdownDirection: ({ anchorRect, panelHeight, viewportHeight, gap, }: ResolveDropdownDirectionInput) => PortalDirection;
-export type BuildPortalPanelStyleInput = Readonly<{
+export declare const resolveDropdownDirection: ({ anchorRect, panelHeight, viewportHeight, gap, }: ResolveDropdownDirectionParams) => PortalDirection;
+export type BuildPortalPanelStyleParams = Readonly<{
     anchorRect: AnchorRect;
     panelHeight: number;
     panelWidth: number | null;
@@ -42,18 +42,15 @@ export type PortalPanelStyle = Readonly<{
     zIndex: number;
     minWidth?: number;
 }>;
-export declare const buildPortalPanelStyle: ({ anchorRect, panelHeight, panelWidth, direction, align, offset, matchAnchorWidth, }: BuildPortalPanelStyleInput) => PortalPanelStyle;
-export type AnchorGeometryObserverOptions = Readonly<{
+export declare const buildPortalPanelStyle: ({ anchorRect, panelHeight, panelWidth, direction, align, offset, matchAnchorWidth, }: BuildPortalPanelStyleParams) => PortalPanelStyle;
+export type ObserveAnchorGeometryParams = Readonly<{
     getAnchor: () => HTMLElement | null;
-    /**
-     * 구독 시점에 1회 호출되어 ResizeObserver 가 부착된다.
-     * 구독 후 패널이 교체·마운트되어도 옵저버는 갱신되지 않는다.
-     */
+    /** ResizeObserver 는 구독 시점의 패널에만 부착된다 — 이후 교체·마운트되어도 옵저버는 갱신되지 않는다. */
     getPanel: () => HTMLElement | null;
     onChange: () => void;
 }>;
-export declare const observeAnchorGeometry: ({ getAnchor, getPanel, onChange, }: AnchorGeometryObserverOptions) => (() => void);
-export type TrackPortalPositionOptions = Readonly<{
+export declare const observeAnchorGeometry: ({ getAnchor, getPanel, onChange }: ObserveAnchorGeometryParams) => (() => void);
+export type TrackPortalPositionParams = Readonly<{
     getAnchor: () => HTMLElement | null;
     getPanel: () => HTMLElement | null;
     /** 함수를 넘기면 갱신마다 다시 읽는다 — 열린 뒤 패널 높이가 변하는 소비자가 방향을 재판정할 수 있다 */
@@ -63,5 +60,5 @@ export type TrackPortalPositionOptions = Readonly<{
     matchAnchorWidth?: boolean;
     onUpdate: (style: PortalPanelStyle) => void;
 }>;
-export declare const trackPortalPosition: ({ onUpdate, ...measureOptions }: TrackPortalPositionOptions) => (() => void);
+export declare const trackPortalPosition: ({ onUpdate, ...measureOptions }: TrackPortalPositionParams) => (() => void);
 export declare const applyPortalPanelStyle: (element: HTMLElement, style: PortalPanelStyle) => void;

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

@@ -47,17 +47,23 @@ export const buildPortalPanelStyle = ({ anchorRect, panelHeight, panelWidth, dir
     // 옵션이 짧으면 앵커 너비, 길면 자연 확장 — Portal 이전 absolute 모드와 동일한 UX.
     return matchAnchorWidth ? { ...base, minWidth: anchorRect.width } : base;
 };
-export const observeAnchorGeometry = ({ getAnchor, getPanel, onChange, }) => {
+export const observeAnchorGeometry = ({ getAnchor, getPanel, onChange }) => {
     const anchor = getAnchor();
     if (anchor === null) {
         return noop;
     }
     onChange();
-    window.addEventListener('scroll', onChange, { passive: true, capture: true });
+    // 패널 내부 스크롤은 anchor 를 움직이지 않는다
+    const onScroll = (event) => {
+        if (event.target instanceof Node && getPanel()?.contains(event.target))
+            return;
+        onChange();
+    };
+    window.addEventListener('scroll', onScroll, { 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('scroll', onScroll, { capture: true });
         window.removeEventListener('resize', onChange);
         for (const observer of observers) {
             observer?.disconnect();
@@ -74,7 +80,6 @@ export const trackPortalPosition = ({ onUpdate, ...measureOptions }) => observeA
         }
     },
 });
-// TODO(#497): vanilla 어댑터 도입 시 소비
 export const applyPortalPanelStyle = (element, style) => {
     element.style.position = style.position;
     element.style.top = `${style.top}px`;

package/dist/types/src/components/forms-and-input/combo-box/utils.d.ts

@@ -0,0 +1,27 @@
+import type { CSSProperties, ReactNode } from 'react';
+type PortalPanelBinding = {
+    className?: string;
+    style?: CSSProperties;
+};
+type DropdownMounts = {
+    inlineDropdown: ReactNode;
+    portaledDropdown: ReactNode;
+};
+type ResolveDropdownMountsParams = {
+    node: ReactNode;
+    shouldPortal: boolean;
+    portalContainer: HTMLElement | null;
+    isOpen: boolean;
+};
+/**
+ * Portal 모드에서만 패널에 `--portal` 클래스와 fixed 좌표를 얹는다.
+ * floatingStyle 이 null 인 초기 레이아웃 직전에는 클래스만 붙지만,
+ * useLayoutEffect 가 paint 전에 좌표를 채우므로 빈 fixed 가 노출되지 않는다.
+ */
+export declare const resolvePortalPanelBinding: (shouldPortal: boolean, floatingStyle: CSSProperties | null) => PortalPanelBinding;
+/**
+ * 패널 노드를 인라인·Portal 두 마운트 지점 중 한 곳에만 넘긴다. 양쪽에 두면 dropdownRef 가
+ * 나중 노드로 덮여 외부 클릭 판정과 키보드 스크롤이 유령 노드를 가리키게 된다.
+ */
+export declare const resolveDropdownMounts: ({ node, shouldPortal, portalContainer, isOpen, }: ResolveDropdownMountsParams) => DropdownMounts;
+export {};

package/dist/types/src/utils/portal-position/portalPosition.d.ts

@@ -2,7 +2,7 @@ export type PortalDirection = 'up' | 'down';
 export type PortalAlign = 'left' | 'right';
 export type AnchorRect = Readonly<Pick<DOMRectReadOnly, 'top' | 'bottom' | 'left' | 'right' | 'width'>>;
 export declare const PORTAL_PANEL_Z_INDEX = 1500;
-export type ComputePortalPositionInput = Readonly<{
+export type ComputePortalPositionParams = Readonly<{
     anchorRect: AnchorRect;
     panelHeight: number;
     panelWidth: number;
@@ -14,15 +14,15 @@ export type PortalPosition = Readonly<{
     top: number;
     left: number;
 }>;
-export declare const computePortalPosition: ({ anchorRect, panelHeight, panelWidth, direction, align, offset, }: ComputePortalPositionInput) => PortalPosition;
-export type ResolveDropdownDirectionInput = Readonly<{
+export declare const computePortalPosition: ({ anchorRect, panelHeight, panelWidth, direction, align, offset, }: ComputePortalPositionParams) => PortalPosition;
+export type ResolveDropdownDirectionParams = Readonly<{
     anchorRect: Pick<AnchorRect, 'bottom'>;
     panelHeight: number;
     viewportHeight: number;
     gap?: number;
 }>;
-export declare const resolveDropdownDirection: ({ anchorRect, panelHeight, viewportHeight, gap, }: ResolveDropdownDirectionInput) => PortalDirection;
-export type BuildPortalPanelStyleInput = Readonly<{
+export declare const resolveDropdownDirection: ({ anchorRect, panelHeight, viewportHeight, gap, }: ResolveDropdownDirectionParams) => PortalDirection;
+export type BuildPortalPanelStyleParams = Readonly<{
     anchorRect: AnchorRect;
     panelHeight: number;
     panelWidth: number | null;
@@ -42,18 +42,15 @@ export type PortalPanelStyle = Readonly<{
     zIndex: number;
     minWidth?: number;
 }>;
-export declare const buildPortalPanelStyle: ({ anchorRect, panelHeight, panelWidth, direction, align, offset, matchAnchorWidth, }: BuildPortalPanelStyleInput) => PortalPanelStyle;
-export type AnchorGeometryObserverOptions = Readonly<{
+export declare const buildPortalPanelStyle: ({ anchorRect, panelHeight, panelWidth, direction, align, offset, matchAnchorWidth, }: BuildPortalPanelStyleParams) => PortalPanelStyle;
+export type ObserveAnchorGeometryParams = Readonly<{
     getAnchor: () => HTMLElement | null;
-    /**
-     * 구독 시점에 1회 호출되어 ResizeObserver 가 부착된다.
-     * 구독 후 패널이 교체·마운트되어도 옵저버는 갱신되지 않는다.
-     */
+    /** ResizeObserver 는 구독 시점의 패널에만 부착된다 — 이후 교체·마운트되어도 옵저버는 갱신되지 않는다. */
     getPanel: () => HTMLElement | null;
     onChange: () => void;
 }>;
-export declare const observeAnchorGeometry: ({ getAnchor, getPanel, onChange, }: AnchorGeometryObserverOptions) => (() => void);
-export type TrackPortalPositionOptions = Readonly<{
+export declare const observeAnchorGeometry: ({ getAnchor, getPanel, onChange }: ObserveAnchorGeometryParams) => (() => void);
+export type TrackPortalPositionParams = Readonly<{
     getAnchor: () => HTMLElement | null;
     getPanel: () => HTMLElement | null;
     /** 함수를 넘기면 갱신마다 다시 읽는다 — 열린 뒤 패널 높이가 변하는 소비자가 방향을 재판정할 수 있다 */
@@ -63,5 +60,5 @@ export type TrackPortalPositionOptions = Readonly<{
     matchAnchorWidth?: boolean;
     onUpdate: (style: PortalPanelStyle) => void;
 }>;
-export declare const trackPortalPosition: ({ onUpdate, ...measureOptions }: TrackPortalPositionOptions) => (() => void);
+export declare const trackPortalPosition: ({ onUpdate, ...measureOptions }: TrackPortalPositionParams) => (() => void);
 export declare const applyPortalPanelStyle: (element: HTMLElement, style: PortalPanelStyle) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ncds/ui-admin",
-  "version": "1.8.25-alpha.2",
+  "version": "1.8.25-alpha.3",
   "description": "nhn-commerce의 어드민 디자인 시스템입니다.",
   "scripts": {
     "barrel": "node barrel.js",