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

package/dist/temp/src/hooks/__tests__/useFloatingPosition.ssr.test.d.ts

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

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

@@ -0,0 +1,26 @@
+// @vitest-environment node
+import { createElement, createRef } from 'react';
+import { renderToString } from 'react-dom/server';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { useFloatingPosition } from '../useFloatingPosition';
+afterEach(() => {
+    vi.restoreAllMocks();
+});
+const FloatingProbe = () => {
+    useFloatingPosition({
+        enabled: true,
+        isOpen: true,
+        triggerRef: createRef(),
+        floatingRef: createRef(),
+        direction: 'down',
+    });
+    return null;
+};
+describe('useFloatingPosition — SSR', () => {
+    it('서버 렌더에서 useLayoutEffect 경고를 내지 않는다', () => {
+        const consoleError = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+        renderToString(createElement(FloatingProbe));
+        const layoutEffectWarnings = consoleError.mock.calls.filter((args) => args.some((arg) => typeof arg === 'string' && arg.includes('useLayoutEffect')));
+        expect(layoutEffectWarnings).toHaveLength(0);
+    });
+});

package/dist/temp/src/hooks/__tests__/useFloatingPosition.test.d.ts

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

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

@@ -0,0 +1,205 @@
+// @vitest-environment jsdom
+import { createElement } from 'react';
+import { createRoot } from 'react-dom/client';
+import { act } from 'react-dom/test-utils';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { trackPortalPosition } from '../../utils/portal-position';
+import { useFloatingPosition } from '../useFloatingPosition';
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+const installResizeObserverStub = () => {
+    class ResizeObserverStub {
+        constructor() {
+            this.observe = vi.fn();
+            this.unobserve = vi.fn();
+            this.disconnect = vi.fn();
+        }
+    }
+    vi.stubGlobal('ResizeObserver', ResizeObserverStub);
+};
+afterEach(() => {
+    document.body.innerHTML = '';
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+});
+const makeAnchorRect = (overrides = {}) => ({
+    top: 100,
+    bottom: 140,
+    left: 50,
+    right: 250,
+    width: 200,
+    ...overrides,
+});
+const PANEL_HEIGHT = 300;
+const PANEL_WIDTH = 180;
+const DEFAULT_OFFSET = 4;
+const CHANGED_OFFSET = 12;
+const EXPECTED_Z_INDEX = 1500;
+const toDomRect = (rect) => DOMRect.fromRect({ x: rect.left, y: rect.top, width: rect.width, height: rect.bottom - rect.top });
+const createAnchor = (rect = makeAnchorRect()) => {
+    const element = document.createElement('button');
+    document.body.appendChild(element);
+    vi.spyOn(element, 'getBoundingClientRect').mockReturnValue(toDomRect(rect));
+    return element;
+};
+const createPanel = () => {
+    const element = document.createElement('div');
+    document.body.appendChild(element);
+    Object.defineProperty(element, 'offsetHeight', { value: PANEL_HEIGHT, configurable: true });
+    Object.defineProperty(element, 'offsetWidth', { value: PANEL_WIDTH, configurable: true });
+    return element;
+};
+const makeRef = (element) => ({ current: element });
+const Probe = ({ params, record }) => {
+    record(useFloatingPosition(params));
+    return null;
+};
+const renderHook = (initialParams) => {
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    const root = createRoot(container);
+    const record = vi.fn();
+    const rerender = (params) => {
+        act(() => {
+            root.render(createElement(Probe, { params, record }));
+        });
+    };
+    rerender(initialParams);
+    const unmount = () => {
+        act(() => {
+            root.unmount();
+        });
+        container.remove();
+    };
+    return { rerender, unmount, latest: () => record.mock.lastCall?.[0] };
+};
+const baseParams = (overrides = {}) => ({
+    enabled: true,
+    isOpen: true,
+    triggerRef: makeRef(null),
+    floatingRef: makeRef(null),
+    direction: 'down',
+    ...overrides,
+});
+const dispatchScroll = () => {
+    act(() => {
+        window.dispatchEvent(new Event('scroll'));
+    });
+};
+describe('useFloatingPosition ↔ trackPortalPosition 동등성 (E-1)', () => {
+    it.each([
+        { direction: 'down', align: 'left', matchTriggerWidth: false },
+        { direction: 'down', align: 'right', matchTriggerWidth: false },
+        { direction: 'up', align: 'left', matchTriggerWidth: true },
+        { direction: 'up', align: 'right', matchTriggerWidth: true },
+    ])('direction=$direction · align=$align · matchTriggerWidth=$matchTriggerWidth 에서 훅 style 과 onUpdate 인자가 같다', ({ direction, align, matchTriggerWidth }) => {
+        installResizeObserverStub();
+        const anchor = createAnchor();
+        const panel = createPanel();
+        const onUpdate = vi.fn();
+        const hook = renderHook(baseParams({ triggerRef: makeRef(anchor), floatingRef: makeRef(panel), direction, align, matchTriggerWidth }));
+        const cleanup = trackPortalPosition({
+            getAnchor: () => anchor,
+            getPanel: () => panel,
+            direction,
+            align,
+            matchAnchorWidth: matchTriggerWidth,
+            onUpdate,
+        });
+        expect(hook.latest()).toEqual(onUpdate.mock.lastCall?.[0]);
+        expect(hook.latest()).toMatchObject({ position: 'fixed', zIndex: EXPECTED_Z_INDEX });
+        cleanup();
+        hook.unmount();
+    });
+});
+describe('useFloatingPosition — 비활성 (E-2)', () => {
+    it('enabled=false 이면 null 을 반환한다', () => {
+        installResizeObserverStub();
+        const hook = renderHook(baseParams({ enabled: false, triggerRef: makeRef(createAnchor()), floatingRef: makeRef(createPanel()) }));
+        expect(hook.latest()).toBeNull();
+        hook.unmount();
+    });
+    it('isOpen=false 이면 null 을 반환한다', () => {
+        installResizeObserverStub();
+        const hook = renderHook(baseParams({ isOpen: false, triggerRef: makeRef(createAnchor()), floatingRef: makeRef(createPanel()) }));
+        expect(hook.latest()).toBeNull();
+        hook.unmount();
+    });
+    it('열린 뒤 닫히면 style 이 null 로 돌아간다', () => {
+        installResizeObserverStub();
+        const triggerRef = makeRef(createAnchor());
+        const hook = renderHook(baseParams({ triggerRef }));
+        expect(hook.latest()).not.toBeNull();
+        hook.rerender(baseParams({ triggerRef, isOpen: false }));
+        expect(hook.latest()).toBeNull();
+        hook.unmount();
+    });
+});
+describe('useFloatingPosition — 트리거 부재 (E-3)', () => {
+    it('triggerRef.current 가 null 이면 scroll·resize 리스너를 붙이지 않고 style 은 null 로 남는다', () => {
+        installResizeObserverStub();
+        const addEventListener = vi.spyOn(window, 'addEventListener');
+        const hook = renderHook(baseParams({ triggerRef: makeRef(null) }));
+        const positionListeners = addEventListener.mock.calls.filter(([type]) => type === 'scroll' || type === 'resize');
+        expect(positionListeners).toHaveLength(0);
+        expect(hook.latest()).toBeNull();
+        hook.unmount();
+    });
+    it('산출된 뒤 트리거가 사라지면 이전 style 을 유지한다', () => {
+        installResizeObserverStub();
+        const triggerRef = makeRef(createAnchor());
+        const hook = renderHook(baseParams({ triggerRef, offset: DEFAULT_OFFSET }));
+        const previous = hook.latest();
+        expect(previous).not.toBeNull();
+        triggerRef.current = null;
+        hook.rerender(baseParams({ triggerRef, offset: CHANGED_OFFSET }));
+        expect(hook.latest()).toEqual(previous);
+        hook.unmount();
+    });
+});
+describe('useFloatingPosition — 패널 지연 마운트 (E-4)', () => {
+    it('effect 시점에 패널이 없다가 마운트되면 scroll 시 panelHeight 가 반영된다', () => {
+        installResizeObserverStub();
+        const rect = makeAnchorRect();
+        const floatingRef = makeRef(null);
+        const hook = renderHook(baseParams({ triggerRef: makeRef(createAnchor(rect)), floatingRef, direction: 'up' }));
+        expect(hook.latest()).toMatchObject({ top: rect.top - DEFAULT_OFFSET });
+        floatingRef.current = createPanel();
+        dispatchScroll();
+        expect(hook.latest()).toMatchObject({ top: rect.top - PANEL_HEIGHT - DEFAULT_OFFSET });
+        hook.unmount();
+    });
+});
+describe('useFloatingPosition — 프롭 변경 재구독 (E-5)', () => {
+    it('align 이 left→right 로 바뀌면 left 를 다시 계산한다', () => {
+        installResizeObserverStub();
+        const rect = makeAnchorRect();
+        const triggerRef = makeRef(createAnchor(rect));
+        const floatingRef = makeRef(createPanel());
+        const hook = renderHook(baseParams({ triggerRef, floatingRef, align: 'left' }));
+        expect(hook.latest()).toMatchObject({ left: rect.left });
+        hook.rerender(baseParams({ triggerRef, floatingRef, align: 'right' }));
+        expect(hook.latest()).toMatchObject({ left: rect.right - PANEL_WIDTH });
+        hook.unmount();
+    });
+    it('offset 이 바뀌면 top 을 다시 계산한다', () => {
+        installResizeObserverStub();
+        const rect = makeAnchorRect();
+        const triggerRef = makeRef(createAnchor(rect));
+        const hook = renderHook(baseParams({ triggerRef, offset: DEFAULT_OFFSET }));
+        expect(hook.latest()).toMatchObject({ top: rect.bottom + DEFAULT_OFFSET });
+        hook.rerender(baseParams({ triggerRef, offset: CHANGED_OFFSET }));
+        expect(hook.latest()).toMatchObject({ top: rect.bottom + CHANGED_OFFSET });
+        hook.unmount();
+    });
+    it('matchTriggerWidth=true 이면 minWidth 를 트리거 너비로 낸다', () => {
+        installResizeObserverStub();
+        const rect = makeAnchorRect();
+        const hook = renderHook(baseParams({
+            triggerRef: makeRef(createAnchor(rect)),
+            floatingRef: makeRef(createPanel()),
+            matchTriggerWidth: true,
+        }));
+        expect(hook.latest()).toMatchObject({ minWidth: rect.width });
+        hook.unmount();
+    });
+});

package/dist/temp/src/hooks/dropdown/useDropdown.d.ts

@@ -2,6 +2,8 @@ import { type RefObject } from 'react';
 interface UseDropdownConfig<T = any> {
     triggerRef: RefObject<HTMLElement>;
     dropdownRef?: RefObject<HTMLElement>;
+    /** direction 계산 전용 ref. 미지정 시 triggerRef 사용. Portal 모드에서 anchor box 가 다를 때 지정. */
+    positionRef?: RefObject<HTMLElement>;
     maxHeight: number;
     itemCount: number;
     optionItems: T[];
@@ -15,7 +17,7 @@ interface UseDropdownConfig<T = any> {
  */
 export declare const useDropdown: <T = any>(config: UseDropdownConfig<T>) => {
     isOpen: boolean;
-    direction: import("../../types").DropdownDirection;
+    direction: import("../../utils/portal-position").PortalDirection;
     focusedIndex: number;
     toggleDropdown: () => void;
     closeDropdown: () => void;

package/dist/temp/src/hooks/dropdown/useDropdown.js

@@ -7,12 +7,12 @@ import { useWindowResize } from './useWindowResize';
  * 드롭다운 기능을 통합한 커스텀 훅
  */
 export const useDropdown = (config) => {
-    const { triggerRef, dropdownRef, maxHeight, itemCount, optionItems, disabled = false, multiple = false, onSelect, onChange, } = config;
+    const { triggerRef, dropdownRef, positionRef, maxHeight, itemCount, optionItems, disabled = false, multiple = false, onSelect, onChange, } = config;
     const [isOpen, setIsOpen] = useState(false);
     const [focusedIndex, setFocusedIndex] = useState(-1);
     // 드롭다운 위치 계산
     const { direction, updatePosition } = useDropdownPosition({
-        triggerRef,
+        triggerRef: positionRef ?? triggerRef,
         maxHeight,
         itemCount,
     });

package/dist/temp/src/hooks/dropdown/useDropdownPosition.d.ts

@@ -1,9 +1,9 @@
-import type { DropdownDirection, DropdownPositionConfig } from '../../types/dropdown';
+import type { DropdownPositionConfig } from '../../types/dropdown';
 /**
  * 드롭다운 위치 계산을 위한 커스텀 훅
  */
 export declare const useDropdownPosition: (config: DropdownPositionConfig) => {
-    direction: DropdownDirection;
+    direction: import("../../utils/portal-position").PortalDirection;
     updatePosition: () => import("../../types/dropdown").DropdownPositionResult;
-    setDirection: import("react").Dispatch<import("react").SetStateAction<DropdownDirection>>;
+    setDirection: import("react").Dispatch<import("react").SetStateAction<import("../../utils/portal-position").PortalDirection>>;
 };

package/dist/temp/src/hooks/useFloatingPosition.d.ts

@@ -1,15 +1,17 @@
 import { type CSSProperties, type RefObject } from 'react';
-type FloatingDirection = 'up' | 'down';
+import { type PortalAlign, type PortalDirection } from '../utils/portal-position';
 type UseFloatingPositionParams = {
     enabled: boolean;
     isOpen: boolean;
     triggerRef: RefObject<HTMLElement | null>;
     floatingRef: RefObject<HTMLElement | null>;
-    direction: FloatingDirection;
+    direction: PortalDirection;
+    /** trigger 와 floating 요소 사이 간격. 미지정 시 4px */
     offset?: number;
-    align?: 'left' | 'right';
+    /** 미지정 시 'left' */
+    align?: PortalAlign;
     /**
-     * true면 floating 요소의 width를 trigger 너비에 맞춘다.
+     * true면 floating 요소의 min-width를 trigger 너비로 보장한다 (width 고정이 아니다).
      * Portal 모드에서 부모가 body로 바뀌면서 min-width: 100% 같은 CSS가 viewport 너비로
      * 폭주하는 것을 막는다 (예: SelectBox 옵션 패널).
      */

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

@@ -1,55 +1,22 @@
-import { useLayoutEffect, useState } from 'react';
-const FLOATING_Z_INDEX = 1500;
-export const useFloatingPosition = ({ enabled, isOpen, triggerRef, floatingRef, direction, offset = 4, align = 'left', matchTriggerWidth = false, }) => {
+import { useState } from 'react';
+import { trackPortalPosition } from '../utils/portal-position';
+import { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect';
+export const useFloatingPosition = ({ enabled, isOpen, triggerRef, floatingRef, direction, offset, align, matchTriggerWidth = false, }) => {
     const [style, setStyle] = useState(null);
-    useLayoutEffect(() => {
+    useIsomorphicLayoutEffect(() => {
         if (!enabled || !isOpen) {
             setStyle(null);
             return;
         }
-        const trigger = triggerRef.current;
-        if (!trigger)
-            return;
-        const calculatePosition = (trigger, floatingHeight, floatingWidth) => {
-            const top = direction === 'up' ? trigger.top - floatingHeight - offset : trigger.bottom + offset;
-            const left = align === 'right' ? trigger.right - floatingWidth : trigger.left;
-            return { top, left };
-        };
-        const update = () => {
-            const t = triggerRef.current;
-            const f = floatingRef.current;
-            if (!t)
-                return;
-            const r = t.getBoundingClientRect();
-            const floatingHeight = f?.offsetHeight ?? 0;
-            const floatingWidth = matchTriggerWidth ? r.width : (f?.offsetWidth ?? r.width);
-            const { top, left } = calculatePosition(r, floatingHeight, floatingWidth);
-            // matchTriggerWidth=true: width는 max-content(콘텐츠 자연 너비), min-width만 trigger 너비로 보장.
-            // 옵션이 짧으면 trigger 너비, 길면 자연 확장 — 기존 absolute 모드와 동일한 UX.
-            setStyle({
-                position: 'fixed',
-                top,
-                left,
-                zIndex: FLOATING_Z_INDEX,
-                ...(matchTriggerWidth ? { minWidth: r.width } : {}),
-            });
-        };
-        update();
-        window.addEventListener('scroll', update, true);
-        window.addEventListener('resize', update);
-        const triggerObserver = new ResizeObserver(update);
-        triggerObserver.observe(trigger);
-        let floatingObserver;
-        if (floatingRef.current) {
-            floatingObserver = new ResizeObserver(update);
-            floatingObserver.observe(floatingRef.current);
-        }
-        return () => {
-            window.removeEventListener('scroll', update, true);
-            window.removeEventListener('resize', update);
-            triggerObserver.disconnect();
-            floatingObserver?.disconnect();
-        };
+        return trackPortalPosition({
+            getAnchor: () => triggerRef.current,
+            getPanel: () => floatingRef.current,
+            direction,
+            align,
+            offset,
+            matchAnchorWidth: matchTriggerWidth,
+            onUpdate: setStyle,
+        });
     }, [enabled, isOpen, direction, offset, align, matchTriggerWidth, triggerRef, floatingRef]);
     return style;
 };

package/dist/temp/src/types/dropdown/dropdown.d.ts

@@ -1,5 +1,6 @@
 import type { RefObject } from 'react';
-export type DropdownDirection = 'up' | 'down';
+import type { PortalDirection } from '../../utils/portal-position';
+export type DropdownDirection = PortalDirection;
 export type DropdownPositionConfig = {
     triggerRef: RefObject<HTMLElement>;
     maxHeight: number;

package/dist/temp/src/utils/dropdown/__tests__/dropdownUtils.test.d.ts

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

package/dist/temp/src/utils/dropdown/__tests__/dropdownUtils.test.js

@@ -0,0 +1,174 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { adjustDropdownPosition, calculateDropdownPosition, calculateNextFocusIndex, findScrollableParent, } from '../dropdownUtils';
+afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+});
+const VIEWPORT_HEIGHT = 800;
+const MAX_HEIGHT = 300;
+const ITEM_HEIGHT = 40;
+const ITEM_COUNT = 10;
+const PANEL_HEIGHT = Math.min(MAX_HEIGHT, ITEM_COUNT * ITEM_HEIGHT);
+const DEFAULT_GAP = 20;
+const EXTRA_SPACE = 200;
+const SHORTFALL = 100;
+const TRIGGER_HEIGHT = 40;
+const TRIGGER_WIDTH = 200;
+const createTriggerRef = ({ bottom }) => {
+    const element = document.createElement('button');
+    vi.spyOn(element, 'getBoundingClientRect').mockReturnValue(DOMRect.fromRect({ x: 0, y: bottom - TRIGGER_HEIGHT, width: TRIGGER_WIDTH, height: TRIGGER_HEIGHT }));
+    return { current: element };
+};
+const nullTriggerRef = () => ({ current: null });
+describe('calculateDropdownPosition — 위임 후 반환 불변 (E-9)', () => {
+    it('triggerRef.current 가 null 이면 down · maxHeight 를 그대로 반환한다', () => {
+        vi.stubGlobal('innerHeight', VIEWPORT_HEIGHT);
+        const result = calculateDropdownPosition({
+            triggerRef: nullTriggerRef(),
+            maxHeight: MAX_HEIGHT,
+            itemCount: ITEM_COUNT,
+        });
+        expect(result).toEqual({ direction: 'down', maxHeight: MAX_HEIGHT });
+    });
+    it.each([
+        { label: '공간 충분', spaceBelow: PANEL_HEIGHT + EXTRA_SPACE, direction: 'down' },
+        { label: '공간 부족', spaceBelow: PANEL_HEIGHT - SHORTFALL, direction: 'up' },
+        { label: '경계 (panelHeight+20)', spaceBelow: PANEL_HEIGHT + DEFAULT_GAP, direction: 'down' },
+        { label: '경계 -1 (panelHeight+19)', spaceBelow: PANEL_HEIGHT + DEFAULT_GAP - 1, direction: 'up' },
+        { label: '경계 +1 (panelHeight+21)', spaceBelow: PANEL_HEIGHT + DEFAULT_GAP + 1, direction: 'down' },
+    ])('$label → $direction', ({ spaceBelow, direction }) => {
+        vi.stubGlobal('innerHeight', VIEWPORT_HEIGHT);
+        const result = calculateDropdownPosition({
+            triggerRef: createTriggerRef({ bottom: VIEWPORT_HEIGHT - spaceBelow }),
+            maxHeight: MAX_HEIGHT,
+            itemCount: ITEM_COUNT,
+            itemHeight: ITEM_HEIGHT,
+        });
+        expect(result).toEqual({ direction, maxHeight: MAX_HEIGHT });
+    });
+    it('itemCount×itemHeight 가 maxHeight 보다 작으면 그 값을 패널 높이로 쓴다', () => {
+        vi.stubGlobal('innerHeight', VIEWPORT_HEIGHT);
+        const shortPanelHeight = 2 * ITEM_HEIGHT;
+        const result = calculateDropdownPosition({
+            triggerRef: createTriggerRef({ bottom: VIEWPORT_HEIGHT - (shortPanelHeight + DEFAULT_GAP) }),
+            maxHeight: MAX_HEIGHT,
+            itemCount: 2,
+            itemHeight: ITEM_HEIGHT,
+        });
+        expect(result.direction).toBe('down');
+    });
+    it('offset 을 지정하면 그 간격으로 반전 여부를 판정한다', () => {
+        vi.stubGlobal('innerHeight', VIEWPORT_HEIGHT);
+        const result = calculateDropdownPosition({
+            triggerRef: createTriggerRef({ bottom: VIEWPORT_HEIGHT - (PANEL_HEIGHT + DEFAULT_GAP) }),
+            maxHeight: MAX_HEIGHT,
+            itemCount: ITEM_COUNT,
+            itemHeight: ITEM_HEIGHT,
+            offset: DEFAULT_GAP + 1,
+        });
+        expect(result.direction).toBe('up');
+    });
+});
+describe('calculateNextFocusIndex — 순환 포커스 이동 (characterisation)', () => {
+    const LENGTH = 5;
+    const LAST = LENGTH - 1;
+    it('옵션이 없으면 -1 을 반환한다', () => {
+        expect(calculateNextFocusIndex(0, 'down', 0)).toBe(-1);
+        expect(calculateNextFocusIndex(2, 'up', 0)).toBe(-1);
+    });
+    it.each([
+        { label: 'down · 중간', current: 2, direction: 'down', expected: 3 },
+        { label: 'down · 마지막 → 첫 번째로 순환', current: LAST, direction: 'down', expected: 0 },
+        { label: 'up · 중간', current: 2, direction: 'up', expected: 1 },
+        { label: 'up · 첫 번째 → 마지막으로 순환', current: 0, direction: 'up', expected: LAST },
+        { label: 'up · 초기값 -1 → 마지막', current: -1, direction: 'up', expected: LAST },
+    ])('$label', ({ current, direction, expected }) => {
+        expect(calculateNextFocusIndex(current, direction, LENGTH)).toBe(expected);
+    });
+});
+const VIEWPORT_WIDTH = 1000;
+const EDGE_MARGIN = 10;
+const createDropdownElement = (rect) => {
+    const element = document.createElement('div');
+    vi.spyOn(element, 'getBoundingClientRect').mockReturnValue(DOMRect.fromRect({ x: rect.left, y: rect.bottom - rect.height, width: rect.right - rect.left, height: rect.height }));
+    return element;
+};
+describe('adjustDropdownPosition — 뷰포트 이탈 보정 (characterisation)', () => {
+    it('뷰포트 안에 있으면 style 을 변경하지 않는다', () => {
+        vi.stubGlobal('innerWidth', VIEWPORT_WIDTH);
+        vi.stubGlobal('innerHeight', VIEWPORT_HEIGHT);
+        const element = createDropdownElement({ left: 100, right: 300, bottom: 400, height: 200 });
+        adjustDropdownPosition(element);
+        expect(element.style.left).toBe('');
+        expect(element.style.maxHeight).toBe('');
+    });
+    it('우측 이탈 시 초과분 + 여백만큼 left 를 음수로 이동한다', () => {
+        vi.stubGlobal('innerWidth', VIEWPORT_WIDTH);
+        vi.stubGlobal('innerHeight', VIEWPORT_HEIGHT);
+        const overflow = 50;
+        const element = createDropdownElement({ left: 800, right: VIEWPORT_WIDTH + overflow, bottom: 400, height: 200 });
+        adjustDropdownPosition(element);
+        expect(element.style.left).toBe(`${-overflow - EDGE_MARGIN}px`);
+    });
+    it('좌측 이탈 시 left 를 여백값으로 고정한다', () => {
+        vi.stubGlobal('innerWidth', VIEWPORT_WIDTH);
+        vi.stubGlobal('innerHeight', VIEWPORT_HEIGHT);
+        const element = createDropdownElement({ left: -30, right: 170, bottom: 400, height: 200 });
+        adjustDropdownPosition(element);
+        expect(element.style.left).toBe(`${EDGE_MARGIN}px`);
+    });
+    it('하단 이탈 시 초과분 + 여백만큼 maxHeight 를 줄인다', () => {
+        vi.stubGlobal('innerWidth', VIEWPORT_WIDTH);
+        vi.stubGlobal('innerHeight', VIEWPORT_HEIGHT);
+        const overflow = 60;
+        const height = 200;
+        const element = createDropdownElement({ left: 100, right: 300, bottom: VIEWPORT_HEIGHT + overflow, height });
+        adjustDropdownPosition(element);
+        expect(element.style.maxHeight).toBe(`${height - overflow - EDGE_MARGIN}px`);
+    });
+});
+const CLIENT_HEIGHT = 100;
+const OVERFLOWING_SCROLL_HEIGHT = 500;
+const createScrollable = ({ overflowY, scrollable }) => {
+    const element = document.createElement('div');
+    element.style.overflowY = overflowY;
+    Object.defineProperty(element, 'scrollHeight', {
+        value: scrollable ? OVERFLOWING_SCROLL_HEIGHT : CLIENT_HEIGHT,
+        configurable: true,
+    });
+    Object.defineProperty(element, 'clientHeight', { value: CLIENT_HEIGHT, configurable: true });
+    return element;
+};
+const mountChain = (...chain) => {
+    chain.reduce((parent, child) => {
+        parent.appendChild(child);
+        return child;
+    });
+    document.body.appendChild(chain[0]);
+    return chain;
+};
+describe('findScrollableParent — 스크롤 부모 탐색 (characterisation)', () => {
+    afterEach(() => {
+        document.body.innerHTML = '';
+    });
+    it('boundary 이전에 overflow auto 이고 내용이 넘치는 조상이 있으면 그 요소를 반환한다', () => {
+        const [boundary, scrollParent, , target] = mountChain(createScrollable({ overflowY: 'visible', scrollable: false }), createScrollable({ overflowY: 'auto', scrollable: true }), createScrollable({ overflowY: 'visible', scrollable: false }), createScrollable({ overflowY: 'visible', scrollable: false }));
+        expect(findScrollableParent(target, boundary)).toBe(scrollParent);
+    });
+    it('overflow scroll 이어도 내용이 넘치지 않으면 건너뛴다', () => {
+        const [boundary, , target] = mountChain(createScrollable({ overflowY: 'visible', scrollable: false }), createScrollable({ overflowY: 'scroll', scrollable: false }), createScrollable({ overflowY: 'visible', scrollable: false }));
+        expect(findScrollableParent(target, boundary)).toBeNull();
+    });
+    it('조상 중 없고 boundary 자체가 스크롤 가능하면 boundary 를 반환한다', () => {
+        const [boundary, , target] = mountChain(createScrollable({ overflowY: 'auto', scrollable: true }), createScrollable({ overflowY: 'visible', scrollable: false }), createScrollable({ overflowY: 'visible', scrollable: false }));
+        expect(findScrollableParent(target, boundary)).toBe(boundary);
+    });
+    it('boundary 까지 스크롤 가능한 요소가 없으면 null 을 반환한다', () => {
+        const [boundary, target] = mountChain(createScrollable({ overflowY: 'hidden', scrollable: true }), createScrollable({ overflowY: 'visible', scrollable: false }));
+        expect(findScrollableParent(target, boundary)).toBeNull();
+    });
+    it('element 가 boundary 자신이면 boundary 의 스크롤 가능 여부로만 판정한다', () => {
+        const [boundary] = mountChain(createScrollable({ overflowY: 'scroll', scrollable: true }));
+        expect(findScrollableParent(boundary, boundary)).toBe(boundary);
+    });
+});

package/dist/temp/src/utils/dropdown/dropdownUtils.js

@@ -1,3 +1,4 @@
+import { resolveDropdownDirection } from '../portal-position';
 /**
  * 드롭다운 위치를 계산하는 유틸리티 함수
  */
@@ -5,15 +6,13 @@ export const calculateDropdownPosition = ({ triggerRef, maxHeight, itemCount, it
     if (!triggerRef?.current) {
         return { direction: 'down', maxHeight };
     }
-    const rect = triggerRef?.current.getBoundingClientRect();
-    const viewportHeight = window.innerHeight;
-    const dropdownHeight = Math.min(maxHeight, itemCount * itemHeight);
-    // 아래쪽 공간이 충분한지 확인
-    const spaceBelow = viewportHeight - rect.bottom;
-    if (spaceBelow < dropdownHeight + offset) {
-        return { direction: 'up', maxHeight };
-    }
-    return { direction: 'down', maxHeight };
+    const direction = resolveDropdownDirection({
+        anchorRect: triggerRef.current.getBoundingClientRect(),
+        panelHeight: Math.min(maxHeight, itemCount * itemHeight),
+        viewportHeight: window.innerHeight,
+        gap: offset,
+    });
+    return { direction, maxHeight };
 };
 /**
  * 키보드 네비게이션을 위한 포커스 인덱스 계산

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

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