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

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

@@ -0,0 +1,181 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import { buildPortalPanelStyle, computePortalPosition, PORTAL_PANEL_Z_INDEX, resolveDropdownDirection, } from '..';
+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 CUSTOM_OFFSET = 10;
+const DEFAULT_GAP = 20;
+const EXPECTED_Z_INDEX = 1500;
+const VIEWPORT_HEIGHT = 800;
+describe('portalPosition — 모듈 로드 (P-8)', () => {
+    it('Node 환경에서 window 없이 import 된다', () => {
+        expect(typeof window).toBe('undefined');
+        expect(computePortalPosition).toBeTypeOf('function');
+        expect(resolveDropdownDirection).toBeTypeOf('function');
+        expect(buildPortalPanelStyle).toBeTypeOf('function');
+    });
+});
+describe('computePortalPosition — 좌표 공식 (P-1)', () => {
+    const anchorRect = makeAnchorRect();
+    it.each([
+        { direction: 'down', align: 'left', top: 144, left: 50 },
+        { direction: 'down', align: 'right', top: 144, left: 70 },
+        { direction: 'up', align: 'left', top: -204, left: 50 },
+        { direction: 'up', align: 'right', top: -204, left: 70 },
+    ])('direction=$direction · align=$align → top=$top · left=$left', ({ direction, align, top, left }) => {
+        const position = computePortalPosition({
+            anchorRect,
+            panelHeight: PANEL_HEIGHT,
+            panelWidth: PANEL_WIDTH,
+            direction,
+            align,
+            offset: DEFAULT_OFFSET,
+        });
+        expect(position).toEqual({ top, left });
+    });
+});
+describe('computePortalPosition — 기본값 (P-2)', () => {
+    it('offset 을 생략하면 4px 을 적용한다', () => {
+        const anchorRect = makeAnchorRect();
+        const position = computePortalPosition({
+            anchorRect,
+            panelHeight: PANEL_HEIGHT,
+            panelWidth: PANEL_WIDTH,
+            direction: 'down',
+        });
+        expect(position.top).toBe(anchorRect.bottom + DEFAULT_OFFSET);
+    });
+    it('align 을 생략하면 left 정렬로 산출한다', () => {
+        const anchorRect = makeAnchorRect();
+        const position = computePortalPosition({
+            anchorRect,
+            panelHeight: PANEL_HEIGHT,
+            panelWidth: PANEL_WIDTH,
+            direction: 'down',
+        });
+        expect(position.left).toBe(anchorRect.left);
+    });
+    it('offset 을 지정하면 그 값으로 간격을 계산한다', () => {
+        const anchorRect = makeAnchorRect();
+        const down = computePortalPosition({
+            anchorRect,
+            panelHeight: PANEL_HEIGHT,
+            panelWidth: PANEL_WIDTH,
+            direction: 'down',
+            offset: CUSTOM_OFFSET,
+        });
+        const up = computePortalPosition({
+            anchorRect,
+            panelHeight: PANEL_HEIGHT,
+            panelWidth: PANEL_WIDTH,
+            direction: 'up',
+            offset: CUSTOM_OFFSET,
+        });
+        expect(down.top).toBe(anchorRect.bottom + CUSTOM_OFFSET);
+        expect(up.top).toBe(anchorRect.top - PANEL_HEIGHT - CUSTOM_OFFSET);
+    });
+});
+describe('buildPortalPanelStyle — 스타일 조립 (P-3)', () => {
+    it('matchAnchorWidth=false 이고 panelWidth 가 숫자면 그 너비로 계산하고 minWidth 를 내지 않는다', () => {
+        const anchorRect = makeAnchorRect();
+        const style = buildPortalPanelStyle({
+            anchorRect,
+            panelHeight: PANEL_HEIGHT,
+            panelWidth: PANEL_WIDTH,
+            direction: 'down',
+            align: 'right',
+        });
+        expect(style.left).toBe(anchorRect.right - PANEL_WIDTH);
+        expect(style).not.toHaveProperty('minWidth');
+    });
+    it('matchAnchorWidth=false 이고 panelWidth 가 null 이면 anchor 너비로 대체하고 minWidth 를 내지 않는다', () => {
+        const anchorRect = makeAnchorRect();
+        const style = buildPortalPanelStyle({
+            anchorRect,
+            panelHeight: PANEL_HEIGHT,
+            panelWidth: null,
+            direction: 'down',
+            align: 'right',
+        });
+        expect(style.left).toBe(anchorRect.right - anchorRect.width);
+        expect(style).not.toHaveProperty('minWidth');
+    });
+    it('matchAnchorWidth=true 이면 panelWidth 를 무시하고 anchor 너비를 minWidth 로 낸다 — align:right 조합에서 콘텐츠가 앵커보다 넓으면 우측 정렬이 보장되지 않는다', () => {
+        const anchorRect = makeAnchorRect();
+        const style = buildPortalPanelStyle({
+            anchorRect,
+            panelHeight: PANEL_HEIGHT,
+            panelWidth: PANEL_WIDTH,
+            direction: 'down',
+            align: 'right',
+            matchAnchorWidth: true,
+        });
+        expect(style.left).toBe(anchorRect.right - anchorRect.width);
+        expect(style.minWidth).toBe(anchorRect.width);
+    });
+    it('direction=up 이면 panelHeight 만큼 위로 올린 top 을 낸다', () => {
+        const anchorRect = makeAnchorRect();
+        const style = buildPortalPanelStyle({
+            anchorRect,
+            panelHeight: PANEL_HEIGHT,
+            panelWidth: PANEL_WIDTH,
+            direction: 'up',
+        });
+        expect(style.top).toBe(anchorRect.top - PANEL_HEIGHT - DEFAULT_OFFSET);
+    });
+});
+describe('buildPortalPanelStyle — 고정 필드 (P-4)', () => {
+    it('position 은 fixed, zIndex 는 PORTAL_PANEL_Z_INDEX(1500) 이다', () => {
+        const style = buildPortalPanelStyle({
+            anchorRect: makeAnchorRect(),
+            panelHeight: PANEL_HEIGHT,
+            panelWidth: PANEL_WIDTH,
+            direction: 'down',
+        });
+        expect(PORTAL_PANEL_Z_INDEX).toBe(EXPECTED_Z_INDEX);
+        expect(style.position).toBe('fixed');
+        expect(style.zIndex).toBe(EXPECTED_Z_INDEX);
+    });
+    it('PortalPanelStyle 은 CSSProperties 에 할당 가능하다 (P-7)', () => {
+        expectTypeOf().toExtend();
+    });
+});
+describe('resolveDropdownDirection — 경계값 (P-5)', () => {
+    it.each([
+        { spaceBelow: PANEL_HEIGHT + DEFAULT_GAP, expected: 'down' },
+        { spaceBelow: PANEL_HEIGHT + DEFAULT_GAP - 1, expected: 'up' },
+        { spaceBelow: PANEL_HEIGHT + DEFAULT_GAP + 1, expected: 'down' },
+        { spaceBelow: 0, expected: 'up' },
+    ])('spaceBelow=$spaceBelow → $expected', ({ spaceBelow, expected }) => {
+        const direction = resolveDropdownDirection({
+            anchorRect: { bottom: VIEWPORT_HEIGHT - spaceBelow },
+            panelHeight: PANEL_HEIGHT,
+            viewportHeight: VIEWPORT_HEIGHT,
+        });
+        expect(direction).toBe(expected);
+    });
+    it('gap 을 지정하면 그 간격으로 판정한다 (gap=0: 등호는 반전하지 않는다)', () => {
+        const exact = resolveDropdownDirection({
+            anchorRect: { bottom: VIEWPORT_HEIGHT - PANEL_HEIGHT },
+            panelHeight: PANEL_HEIGHT,
+            viewportHeight: VIEWPORT_HEIGHT,
+            gap: 0,
+        });
+        const short = resolveDropdownDirection({
+            anchorRect: { bottom: VIEWPORT_HEIGHT - PANEL_HEIGHT + 1 },
+            panelHeight: PANEL_HEIGHT,
+            viewportHeight: VIEWPORT_HEIGHT,
+            gap: 0,
+        });
+        expect(exact).toBe('down');
+        expect(short).toBe('up');
+    });
+});

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

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

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

@@ -0,0 +1,301 @@
+// @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 = (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 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 = (rect = 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 = ({ height, width } = { 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/temp/src/utils/portal-position/index.d.ts

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

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

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

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

@@ -0,0 +1,67 @@
+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<{
+    anchorRect: AnchorRect;
+    panelHeight: number;
+    panelWidth: number;
+    direction: PortalDirection;
+    align?: PortalAlign;
+    offset?: number;
+}>;
+export type PortalPosition = Readonly<{
+    top: number;
+    left: number;
+}>;
+export declare const computePortalPosition: ({ anchorRect, panelHeight, panelWidth, direction, align, offset, }: ComputePortalPositionInput) => PortalPosition;
+export type ResolveDropdownDirectionInput = 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<{
+    anchorRect: AnchorRect;
+    panelHeight: number;
+    panelWidth: number | null;
+    direction: PortalDirection;
+    align?: PortalAlign;
+    offset?: number;
+    /**
+     * true 이면 panelWidth 를 무시하고 anchorRect.width 로 minWidth 를 설정한다.
+     * align: 'right' 와 조합 시 콘텐츠가 앵커보다 넓으면 우측 정렬이 보장되지 않는다.
+     */
+    matchAnchorWidth?: boolean;
+}>;
+export type PortalPanelStyle = Readonly<{
+    position: 'fixed';
+    top: number;
+    left: number;
+    zIndex: number;
+    minWidth?: number;
+}>;
+export declare const buildPortalPanelStyle: ({ anchorRect, panelHeight, panelWidth, direction, align, offset, matchAnchorWidth, }: BuildPortalPanelStyleInput) => PortalPanelStyle;
+export type AnchorGeometryObserverOptions = Readonly<{
+    getAnchor: () => HTMLElement | null;
+    /**
+     * 구독 시점에 1회 호출되어 ResizeObserver 가 부착된다.
+     * 구독 후 패널이 교체·마운트되어도 옵저버는 갱신되지 않는다.
+     */
+    getPanel: () => HTMLElement | null;
+    onChange: () => void;
+}>;
+export declare const observeAnchorGeometry: ({ getAnchor, getPanel, onChange, }: AnchorGeometryObserverOptions) => (() => void);
+export type TrackPortalPositionOptions = Readonly<{
+    getAnchor: () => HTMLElement | null;
+    getPanel: () => HTMLElement | null;
+    /** 함수를 넘기면 갱신마다 다시 읽는다 — 열린 뒤 패널 높이가 변하는 소비자가 방향을 재판정할 수 있다 */
+    direction: PortalDirection | (() => PortalDirection);
+    align?: PortalAlign;
+    offset?: number;
+    matchAnchorWidth?: boolean;
+    onUpdate: (style: PortalPanelStyle) => void;
+}>;
+export declare const trackPortalPosition: ({ onUpdate, ...measureOptions }: TrackPortalPositionOptions) => (() => void);
+export declare const applyPortalPanelStyle: (element: HTMLElement, style: PortalPanelStyle) => void;

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

@@ -0,0 +1,88 @@
+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 = ({ getAnchor, getPanel, direction, align, offset, matchAnchorWidth, }) => {
+    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 = ({ anchorRect, panelHeight, panelWidth, direction, align = 'left', offset = DEFAULT_OFFSET, }) => ({
+    top: direction === 'up' ? anchorRect.top - panelHeight - offset : anchorRect.bottom + offset,
+    left: align === 'right' ? anchorRect.right - panelWidth : anchorRect.left,
+});
+export const resolveDropdownDirection = ({ anchorRect, panelHeight, viewportHeight, gap = DEFAULT_GAP, }) => viewportHeight - anchorRect.bottom < panelHeight + gap ? 'up' : 'down';
+export const buildPortalPanelStyle = ({ anchorRect, panelHeight, panelWidth, direction, align, offset, matchAnchorWidth = false, }) => {
+    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 = ({ getAnchor, getPanel, onChange, }) => {
+    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 = ({ onUpdate, ...measureOptions }) => 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/types/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/types/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/types/src/components/feedback-and-status/badge/Badge.d.ts

@@ -16,4 +16,4 @@ type BadgeProps = {
 };
 declare const Badge: ({ label, type, color, className, leadingIcon, trailingIcon, size, }: BadgeProps) => import("react/jsx-runtime").JSX.Element;
 export { Badge };
-export type { BadgeType, BadgeColor, BadgeSize, BadgeProps };
+export type { BadgeColor, BadgeProps, BadgeSize, BadgeType };