@ncds/ui-admin 1.8.27 → 1.8.28-alpha.1

package/dist/temp/src/components/overlays/dropdown/__tests__/Dropdown.test.js

@@ -0,0 +1,699 @@
+// @vitest-environment jsdom
+//
+// Dropdown (React) 위험 경로 — 위험 목록표 DD-xx.
+// config 의 순서 변경은 드래그 핸들의 ArrowUp/ArrowDown(onMoveBy) 로 만든다.
+// 드래그앤드롭으로 순서를 바꾸는 경로는 adapter mock 이 필요해 Dropdown.dnd.test.ts 로 분리한다.
+import { DotsVertical, Eye, EyeOff } from '@ncds/ui-admin-icon';
+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 { FloatingProvider } from '../../../../contexts/FloatingContext';
+import { Dropdown, } from '../Dropdown';
+import { applyButtonOf, configItem, configTexts } from './dropdownTestUtils';
+let root = null;
+let container = null;
+/** 테스트가 body 에 직접 붙인 노드 (portalContainer 등) — afterEach 에서 제거 */
+const extraNodes = [];
+const render = (props) => {
+    if (!container) {
+        container = document.createElement('div');
+        document.body.appendChild(container);
+        root = createRoot(container);
+    }
+    act(() => {
+        root?.render(createElement(Dropdown, props));
+    });
+    return container;
+};
+afterEach(() => {
+    if (root) {
+        act(() => {
+            root?.unmount();
+        });
+    }
+    container?.remove();
+    for (const node of extraNodes.splice(0))
+        node.remove();
+    root = null;
+    container = null;
+    vi.restoreAllMocks();
+});
+const click = (element) => {
+    if (!element)
+        throw new Error('click 대상이 없습니다');
+    act(() => {
+        element.click();
+    });
+};
+const keyDown = (element, key) => {
+    if (!element)
+        throw new Error('keydown 대상이 없습니다');
+    act(() => {
+        element.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true }));
+    });
+};
+const openMenu = (view) => {
+    click(view.querySelector('.ncua-dropdown__trigger'));
+};
+// ── config ──────────────────────────────────────────────
+/** a·b 는 노출 토글 대상, c 는 visible 미지정(토글 없음), d 는 required(토글 없음) */
+const createConfigGroups = () => [
+    {
+        sortable: true,
+        items: [
+            { id: 'a', text: '주문번호', visible: true },
+            { id: 'b', text: '상품명', visible: true },
+            { id: 'c', text: '수량' },
+            { id: 'd', text: '주문일', visible: true, required: true },
+        ],
+    },
+];
+const renderConfig = (onApply = vi.fn(), groups = createConfigGroups()) => {
+    const view = render({ variant: 'config', trigger: { type: 'button', text: '컬럼 설정' }, groups, onApply });
+    openMenu(view);
+    return { view, onApply, groups };
+};
+describe('Dropdown config — 적용 (DD-01·02)', () => {
+    it('DD-01 순서 변경·노출 토글 후 적용하면 onApply 에 draft 순서와 visible 이 반영된 items 가 1회 전달된다', () => {
+        const { view, onApply, groups } = renderConfig();
+        keyDown(configItem(view, '주문번호').querySelector('.ncua-dropdown__item-drag-handle'), 'ArrowDown');
+        click(configItem(view, '상품명').querySelector('.ncua-dropdown__item-visibility'));
+        expect(configTexts(view)).toEqual(['상품명', '주문번호', '수량', '주문일']);
+        click(applyButtonOf(view));
+        const [a, b, c, d] = groups[0].items;
+        expect(onApply).toHaveBeenCalledTimes(1);
+        expect(onApply).toHaveBeenCalledWith([{ ...b, visible: false }, a, c, d]);
+    });
+    it('DD-01 visible 이 없는 항목은 visible 필드 없이 원본 그대로 전달된다', () => {
+        const { view, onApply, groups } = renderConfig();
+        keyDown(configItem(view, '수량').querySelector('.ncua-dropdown__item-drag-handle'), 'ArrowUp');
+        click(applyButtonOf(view));
+        const applied = onApply.mock.calls[0][0];
+        expect(applied.map((item) => item.id)).toEqual(['a', 'c', 'b', 'd']);
+        expect(applied[1]).toBe(groups[0].items[2]);
+        expect('visible' in applied[1]).toBe(false);
+    });
+    it('DD-01 여러 그룹의 항목을 하나의 배열로 평탄화해 전달한다', () => {
+        const groups = [
+            { items: [{ id: 'a', text: '주문번호', visible: true }] },
+            { items: [{ id: 'b', text: '상품명', visible: false }] },
+        ];
+        const { view, onApply } = renderConfig(vi.fn(), groups);
+        click(configItem(view, '상품명').querySelector('.ncua-dropdown__item-visibility'));
+        click(applyButtonOf(view));
+        expect(onApply).toHaveBeenCalledWith([groups[0].items[0], { ...groups[1].items[0], visible: true }]);
+    });
+    it('DD-01 적용하면 메뉴가 닫히고 포커스가 트리거로 돌아간다', () => {
+        const { view } = renderConfig();
+        const trigger = view.querySelector('.ncua-dropdown__trigger');
+        click(configItem(view, '주문번호').querySelector('.ncua-dropdown__item-visibility'));
+        click(applyButtonOf(view));
+        expect(view.querySelector('.ncua-dropdown__menu')).toBeNull();
+        expect(document.activeElement).toBe(trigger);
+    });
+    it('DD-01 required 항목과 visible 미지정 항목에는 노출 토글이 없다', () => {
+        const { view } = renderConfig();
+        expect(configItem(view, '주문일').querySelector('.ncua-dropdown__item-visibility')).toBeNull();
+        expect(configItem(view, '수량').querySelector('.ncua-dropdown__item-visibility')).toBeNull();
+        expect(configItem(view, '주문번호').querySelector('.ncua-dropdown__item-visibility')).not.toBeNull();
+    });
+    it('DD-02 변경이 없으면 적용 버튼이 disabled 이고 눌러도 onApply 를 호출하지 않는다', () => {
+        const { view, onApply } = renderConfig();
+        const button = applyButtonOf(view);
+        click(button);
+        expect(button.disabled).toBe(true);
+        expect(onApply).not.toHaveBeenCalled();
+        expect(view.querySelector('.ncua-dropdown__menu')).not.toBeNull();
+    });
+    it('DD-02 노출을 바꾸면 활성화되고 원래대로 되돌리면 다시 disabled 가 된다', () => {
+        const { view } = renderConfig();
+        const toggle = configItem(view, '주문번호').querySelector('.ncua-dropdown__item-visibility');
+        click(toggle);
+        expect(applyButtonOf(view).disabled).toBe(false);
+        click(toggle);
+        expect(applyButtonOf(view).disabled).toBe(true);
+    });
+    it('DD-02 순서를 바꾸면 활성화되고 원래 순서로 되돌리면 다시 disabled 가 된다', () => {
+        const { view } = renderConfig();
+        keyDown(configItem(view, '주문번호').querySelector('.ncua-dropdown__item-drag-handle'), 'ArrowDown');
+        expect(applyButtonOf(view).disabled).toBe(false);
+        keyDown(configItem(view, '주문번호').querySelector('.ncua-dropdown__item-drag-handle'), 'ArrowUp');
+        expect(applyButtonOf(view).disabled).toBe(true);
+    });
+    it('DD-02 범위를 벗어나는 이동(첫 항목 ArrowUp·마지막 항목 ArrowDown)은 변경으로 치지 않는다', () => {
+        const { view } = renderConfig();
+        keyDown(configItem(view, '주문번호').querySelector('.ncua-dropdown__item-drag-handle'), 'ArrowUp');
+        keyDown(configItem(view, '주문일').querySelector('.ncua-dropdown__item-drag-handle'), 'ArrowDown');
+        expect(configTexts(view)).toEqual(['주문번호', '상품명', '수량', '주문일']);
+        expect(applyButtonOf(view).disabled).toBe(true);
+    });
+});
+// ── action ──────────────────────────────────────────────
+describe('Dropdown action — 항목 클릭 (DD-03)', () => {
+    const renderAction = () => {
+        const onEdit = vi.fn();
+        const onDelete = vi.fn();
+        const view = render({
+            trigger: { type: 'button', text: '더보기' },
+            groups: [
+                {
+                    items: [
+                        { id: 'edit', text: '수정', onClick: onEdit },
+                        { id: 'delete', text: '삭제', onClick: onDelete, disabled: true, type: 'danger' },
+                    ],
+                },
+            ],
+        });
+        openMenu(view);
+        const itemOf = (text) => Array.from(view.querySelectorAll('button.ncua-dropdown__item')).find((element) => element.textContent === text);
+        return { view, onEdit, onDelete, itemOf };
+    };
+    it('DD-03 항목을 누르면 그 항목의 onClick 이 1회 호출된다', () => {
+        const { onEdit, onDelete, itemOf } = renderAction();
+        click(itemOf('수정'));
+        expect(onEdit).toHaveBeenCalledTimes(1);
+        expect(onDelete).not.toHaveBeenCalled();
+    });
+    it('DD-03 disabled 항목은 눌러도 onClick 을 호출하지 않고 메뉴도 열린 채로 둔다', () => {
+        const { view, onDelete, itemOf } = renderAction();
+        const item = itemOf('삭제');
+        click(item);
+        // 내부 span 에서 올라온 click 도 막힌다 — 막는 쪽은 컴포넌트의 disabled 검사가 아니라, disabled 버튼의 onClick 을 부르지 않는 React 다
+        act(() => {
+            item?.querySelector('.ncua-dropdown__item-text')?.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+        });
+        expect(item?.disabled).toBe(true);
+        expect(item?.classList.contains('is-disabled')).toBe(true);
+        expect(onDelete).not.toHaveBeenCalled();
+        expect(view.querySelector('.ncua-dropdown__menu')).not.toBeNull();
+    });
+});
+// ── 공통 헬퍼 (DD-07~) ──────────────────────────────────
+const menuOf = (scope = document) => scope.querySelector('.ncua-dropdown__menu');
+const triggerOf = (view) => {
+    const trigger = view.querySelector('.ncua-dropdown__trigger');
+    if (!trigger)
+        throw new Error('trigger 가 없습니다');
+    return trigger;
+};
+const mouseDown = (element) => {
+    act(() => {
+        element.dispatchEvent(new MouseEvent('mousedown', { bubbles: true }));
+    });
+};
+const pressEscape = () => {
+    keyDown(document.body, 'Escape');
+};
+const FakeIcon = ({ className }) => createElement('svg', { className, 'data-icon': 'fake' });
+/** 아이콘 컴포넌트를 따로 렌더한 마크업 — 단언 전에 언마운트까지 끝내 루트가 남지 않는다. */
+const iconMarkupOf = (icon) => {
+    const host = document.createElement('div');
+    const iconRoot = createRoot(host);
+    try {
+        act(() => {
+            iconRoot.render(createElement(icon));
+        });
+        return host.innerHTML;
+    }
+    finally {
+        act(() => {
+            iconRoot.unmount();
+        });
+    }
+};
+const actionItemOf = (view, text) => {
+    const item = Array.from(view.querySelectorAll('button.ncua-dropdown__item')).find((element) => element.querySelector('.ncua-dropdown__item-text')?.textContent === text);
+    if (!item)
+        throw new Error(`action item 이 없습니다: ${text}`);
+    return item;
+};
+const createActionProps = (overrides = {}) => ({
+    trigger: { type: 'button', text: '더보기' },
+    groups: [{ items: [{ id: 'edit', text: '수정', onClick: vi.fn() }] }],
+    ...overrides,
+});
+const createConfigProps = (overrides = {}) => ({
+    variant: 'config',
+    trigger: { type: 'button', text: '컬럼 설정' },
+    groups: createConfigGroups(),
+    onApply: vi.fn(),
+    ...overrides,
+});
+describe('Dropdown config — draft 수명 (DD-07·08)', () => {
+    it('DD-07 적용하지 않고 닫았다가 다시 열면 순서·노출 변경이 버려지고 원래 상태로 돌아간다', () => {
+        const { view, onApply } = renderConfig();
+        keyDown(configItem(view, '주문번호').querySelector('.ncua-dropdown__item-drag-handle'), 'ArrowDown');
+        click(configItem(view, '상품명').querySelector('.ncua-dropdown__item-visibility'));
+        expect(applyButtonOf(view).disabled).toBe(false);
+        openMenu(view); // 트리거 재클릭으로 닫기
+        expect(menuOf(view)).toBeNull();
+        openMenu(view);
+        expect(configTexts(view)).toEqual(['주문번호', '상품명', '수량', '주문일']);
+        expect(configItem(view, '상품명').classList.contains('is-hidden')).toBe(false);
+        expect(applyButtonOf(view).disabled).toBe(true);
+        expect(onApply).not.toHaveBeenCalled();
+    });
+    it('DD-07 Escape 로 닫았다가 다시 열어도 draft 가 초기화된다', () => {
+        const { view } = renderConfig();
+        click(configItem(view, '주문번호').querySelector('.ncua-dropdown__item-visibility'));
+        pressEscape();
+        openMenu(view);
+        expect(configItem(view, '주문번호').classList.contains('is-hidden')).toBe(false);
+        expect(applyButtonOf(view).disabled).toBe(true);
+    });
+    it('DD-08 열린 상태에서 groups 참조만 바뀌면(내용 동일) 편집 중인 draft 가 초기화된다', () => {
+        // 현재 동작 고정 — 결함 후보: #588 (draft 초기화 effect 가 groups 참조에 의존해 인라인 groups 면 편집 유실)
+        const props = createConfigProps();
+        const view = render(props);
+        openMenu(view);
+        keyDown(configItem(view, '주문번호').querySelector('.ncua-dropdown__item-drag-handle'), 'ArrowDown');
+        click(configItem(view, '상품명').querySelector('.ncua-dropdown__item-visibility'));
+        expect(configTexts(view)).toEqual(['상품명', '주문번호', '수량', '주문일']);
+        expect(applyButtonOf(view).disabled).toBe(false);
+        // 부모 리렌더 — inline groups 처럼 내용은 같고 참조만 새 배열
+        render({ ...props, groups: createConfigGroups() });
+        expect(menuOf(view)).not.toBeNull();
+        expect(configTexts(view)).toEqual(['주문번호', '상품명', '수량', '주문일']);
+        expect(configItem(view, '상품명').classList.contains('is-hidden')).toBe(false);
+        expect(applyButtonOf(view).disabled).toBe(true);
+    });
+    it('DD-08 같은 groups 참조로 리렌더하면 draft 가 유지된다', () => {
+        const props = createConfigProps();
+        const view = render(props);
+        openMenu(view);
+        keyDown(configItem(view, '주문번호').querySelector('.ncua-dropdown__item-drag-handle'), 'ArrowDown');
+        render({ ...props, applyButtonText: '저장' });
+        expect(configTexts(view)).toEqual(['상품명', '주문번호', '수량', '주문일']);
+        expect(applyButtonOf(view).disabled).toBe(false);
+    });
+    it.todo('DD-08 열린 상태에서 groups 참조만 바뀌어도(내용 동일) 편집 중인 draft 는 유지되어야 한다');
+});
+describe('Dropdown 열림 상태 (DD-09)', () => {
+    it('DD-09 트리거를 누를 때마다 메뉴가 열리고 닫힌다', () => {
+        const view = render(createActionProps());
+        expect(menuOf(view)).toBeNull();
+        openMenu(view);
+        expect(menuOf(view)).not.toBeNull();
+        openMenu(view);
+        expect(menuOf(view)).toBeNull();
+    });
+    it('DD-09 opened=true 로 마운트하면 처음부터 열려 있다', () => {
+        const view = render(createActionProps({ opened: true }));
+        expect(menuOf(view)).not.toBeNull();
+    });
+    it('DD-09 opened prop 이 바뀌면 열림 상태가 따라간다', () => {
+        const view = render(createActionProps({ opened: false }));
+        render(createActionProps({ opened: true }));
+        expect(menuOf(view)).not.toBeNull();
+        render(createActionProps({ opened: false }));
+        expect(menuOf(view)).toBeNull();
+    });
+    it('DD-09 opened 값이 그대로면 리렌더해도 사용자가 연 상태를 덮어쓰지 않는다', () => {
+        const view = render(createActionProps({ opened: false }));
+        openMenu(view);
+        render(createActionProps({ opened: false, className: 'rerender' }));
+        expect(menuOf(view)).not.toBeNull();
+    });
+});
+describe('Dropdown 바깥 클릭 (DD-10)', () => {
+    it('DD-10 기본값에서 바깥을 mousedown 하면 닫힌다', () => {
+        const view = render(createActionProps());
+        openMenu(view);
+        mouseDown(document.body);
+        expect(menuOf(view)).toBeNull();
+    });
+    it('DD-10 컨테이너 안(트리거·메뉴)을 mousedown 하면 열린 채로 둔다', () => {
+        const view = render(createActionProps());
+        openMenu(view);
+        mouseDown(triggerOf(view));
+        mouseDown(actionItemOf(view, '수정'));
+        expect(menuOf(view)).not.toBeNull();
+    });
+    it('DD-10 portal 메뉴 안을 mousedown 해도 열린 채로 둔다', () => {
+        const view = render(createActionProps({ usePortal: true }));
+        openMenu(view);
+        const menu = menuOf(document.body);
+        if (!menu)
+            throw new Error('portal menu 가 없습니다');
+        mouseDown(actionItemOf(menu, '수정'));
+        expect(menuOf(document.body)).not.toBeNull();
+        expect(menuOf(view)).toBeNull();
+    });
+    it('DD-10 닫힌 상태에서 바깥 mousedown 은 아무 변화가 없다', () => {
+        const view = render(createActionProps());
+        mouseDown(document.body);
+        expect(menuOf(view)).toBeNull();
+    });
+    it('DD-10 closeOnClickOutside=false 면 바깥 mousedown 에도 열린 채로 둔다', () => {
+        const view = render(createActionProps({ closeOnClickOutside: false }));
+        openMenu(view);
+        mouseDown(document.body);
+        expect(menuOf(view)).not.toBeNull();
+    });
+    it('DD-10 언마운트하면 등록했던 mousedown 리스너와 같은 참조를 해제한다', () => {
+        const addSpy = vi.spyOn(document, 'addEventListener');
+        const removeSpy = vi.spyOn(document, 'removeEventListener');
+        render(createActionProps());
+        const handler = addSpy.mock.calls.find(([type]) => type === 'mousedown')?.[1];
+        expect(handler).toBeDefined();
+        act(() => {
+            root?.unmount();
+        });
+        root = null;
+        expect(removeSpy).toHaveBeenCalledWith('mousedown', handler);
+    });
+});
+describe('Dropdown Escape (DD-11)', () => {
+    it('DD-11 열린 상태에서 Escape 를 누르면 닫히고 트리거로 포커스가 돌아간다', () => {
+        const view = render(createActionProps());
+        openMenu(view);
+        actionItemOf(view, '수정').focus();
+        pressEscape();
+        expect(menuOf(view)).toBeNull();
+        expect(document.activeElement).toBe(triggerOf(view));
+    });
+    it('DD-11 Escape 외의 키는 무시한다', () => {
+        const view = render(createActionProps());
+        openMenu(view);
+        keyDown(document.body, 'Enter');
+        expect(menuOf(view)).not.toBeNull();
+    });
+    it('DD-11 닫혀 있는 동안(열기 전·닫은 뒤)의 Escape 는 포커스를 트리거로 옮기지 않는다', () => {
+        const view = render(createActionProps());
+        const outside = document.createElement('button');
+        document.body.appendChild(outside);
+        extraNodes.push(outside);
+        outside.focus();
+        pressEscape();
+        expect(document.activeElement).toBe(outside);
+        openMenu(view);
+        openMenu(view);
+        outside.focus();
+        pressEscape();
+        expect(menuOf(view)).toBeNull();
+        expect(document.activeElement).toBe(outside);
+    });
+    it('DD-11 트리거가 없는(알 수 없는 type) 경우에도 Escape 로 닫힌다', () => {
+        const view = render(createActionProps({ trigger: { type: 'unknown' }, opened: true }));
+        expect(view.querySelector('.ncua-dropdown__trigger')).toBeNull();
+        pressEscape();
+        expect(menuOf(view)).toBeNull();
+    });
+});
+describe('Dropdown action — closeOnClickItem (DD-12)', () => {
+    it('DD-12 기본값(true)에서는 항목을 누르면 메뉴가 닫힌다', () => {
+        const view = render(createActionProps());
+        openMenu(view);
+        click(actionItemOf(view, '수정'));
+        expect(menuOf(view)).toBeNull();
+    });
+    it('DD-12 closeOnClickItem=false 면 onClick 은 호출하고 메뉴는 열린 채로 둔다', () => {
+        const onClick = vi.fn();
+        const view = render(createActionProps({ closeOnClickItem: false, groups: [{ items: [{ id: 'e', text: '수정', onClick }] }] }));
+        openMenu(view);
+        click(actionItemOf(view, '수정'));
+        expect(onClick).toHaveBeenCalledTimes(1);
+        expect(menuOf(view)).not.toBeNull();
+    });
+    it('DD-12 onClick 이 없는 항목은 눌러도 닫히지 않는다', () => {
+        const view = render(createActionProps({ groups: [{ items: [{ id: 'label', text: '라벨' }] }] }));
+        openMenu(view);
+        click(actionItemOf(view, '라벨'));
+        expect(menuOf(view)).not.toBeNull();
+    });
+});
+describe('Dropdown portal (DD-13)', () => {
+    it('DD-13 기본값에서는 컨테이너 안에 렌더하고 --portal 클래스·인라인 위치 스타일이 없다', () => {
+        const view = render(createActionProps());
+        openMenu(view);
+        const menu = menuOf(view);
+        expect(menu?.classList.contains('ncua-dropdown__menu--portal')).toBe(false);
+        expect(menu?.getAttribute('style')).toBeNull();
+    });
+    it('DD-13 usePortal=true 면 body 로 portal 렌더하고 --portal 클래스와 floating 위치 스타일을 붙인다', () => {
+        const view = render(createActionProps({ usePortal: true }));
+        openMenu(view);
+        const menu = menuOf(document.body);
+        expect(menuOf(view)).toBeNull();
+        expect(menu?.parentElement).toBe(document.body);
+        expect(menu?.classList.contains('ncua-dropdown__menu--portal')).toBe(true);
+        expect(menu?.style.position).toBe('fixed');
+    });
+    it('DD-13 FloatingContext.preferPortal=true 면 usePortal 미지정이어도 portalContainer 로 렌더한다', () => {
+        const portalContainer = document.createElement('div');
+        document.body.appendChild(portalContainer);
+        extraNodes.push(portalContainer);
+        container = document.createElement('div');
+        document.body.appendChild(container);
+        root = createRoot(container);
+        const view = container;
+        act(() => {
+            root?.render(createElement(FloatingProvider, { value: { preferPortal: true, portalContainer } }, createElement(Dropdown, createActionProps())));
+        });
+        openMenu(view);
+        expect(menuOf(view)).toBeNull();
+        expect(menuOf(portalContainer)?.classList.contains('ncua-dropdown__menu--portal')).toBe(true);
+    });
+    it('DD-13 FloatingContext.preferPortal=true 여도 usePortal=false 가 우선한다', () => {
+        container = document.createElement('div');
+        document.body.appendChild(container);
+        root = createRoot(container);
+        const view = container;
+        act(() => {
+            root?.render(createElement(FloatingProvider, { value: { preferPortal: true } }, createElement(Dropdown, createActionProps({ usePortal: false }))));
+        });
+        openMenu(view);
+        expect(menuOf(view)?.classList.contains('ncua-dropdown__menu--portal')).toBe(false);
+    });
+});
+describe('Dropdown 역할·접근성 (DD-15)', () => {
+    it('DD-15 config 메뉴는 role=dialog · aria-label="설정" 이다', () => {
+        const { view } = renderConfig();
+        expect(menuOf(view)?.getAttribute('role')).toBe('dialog');
+        expect(menuOf(view)?.getAttribute('aria-label')).toBe('설정');
+    });
+    it('DD-15 action 메뉴는 role=menu 이고 aria-label 이 없다', () => {
+        const view = render(createActionProps());
+        openMenu(view);
+        expect(menuOf(view)?.getAttribute('role')).toBe('menu');
+        expect(menuOf(view)?.hasAttribute('aria-label')).toBe(false);
+    });
+    it('DD-15 노출 토글은 "{text} 노출" aria-label 과 현재 노출 여부를 aria-pressed 로 가진다', () => {
+        const { view } = renderConfig();
+        const toggle = configItem(view, '주문번호').querySelector('.ncua-dropdown__item-visibility');
+        expect(toggle?.getAttribute('aria-label')).toBe('주문번호 노출');
+        expect(toggle?.getAttribute('aria-pressed')).toBe('true');
+        click(toggle);
+        expect(toggle?.getAttribute('aria-pressed')).toBe('false');
+    });
+    it('DD-15 드래그 핸들은 방향키 안내 aria-label 을 가진다', () => {
+        const { view } = renderConfig();
+        expect(configItem(view, '주문번호').querySelector('.ncua-dropdown__item-drag-handle')?.getAttribute('aria-label')).toBe('순서 변경 (위/아래 방향키)');
+    });
+    it('DD-15 핸들에서 방향키 외의 키는 순서를 바꾸지 않는다', () => {
+        const { view } = renderConfig();
+        keyDown(configItem(view, '주문번호').querySelector('.ncua-dropdown__item-drag-handle'), 'Enter');
+        expect(configTexts(view)).toEqual(['주문번호', '상품명', '수량', '주문일']);
+    });
+});
+// ── P2 표현 ──────────────────────────────────────────────
+describe('Dropdown 트리거 종류 (DD-16)', () => {
+    it('DD-16 custom 트리거는 children 을 버튼 안에 렌더한다', () => {
+        const view = render(createActionProps({
+            trigger: { type: 'custom', children: createElement('span', { className: 'custom-child' }, '열기') },
+        }));
+        const trigger = triggerOf(view);
+        expect(trigger.classList.contains('ncua-dropdown__trigger')).toBe(true);
+        expect(trigger.classList.contains('ncua-dropdown__trigger--icon')).toBe(false);
+        expect(trigger.querySelector('.custom-child')?.textContent).toBe('열기');
+        click(trigger);
+        expect(menuOf(view)).not.toBeNull();
+    });
+    it('DD-16 icon 트리거는 icon 미지정 시 DotsVertical 아이콘을 렌더한다', () => {
+        const view = render(createActionProps({ trigger: { type: 'icon' } }));
+        expect(triggerOf(view).classList.contains('ncua-dropdown__trigger--icon')).toBe(true);
+        expect(triggerOf(view).innerHTML).toBe(iconMarkupOf(DotsVertical));
+    });
+    it('DD-16 icon 트리거는 지정한 icon 을 렌더한다', () => {
+        const view = render(createActionProps({ trigger: { type: 'icon', icon: FakeIcon } }));
+        expect(triggerOf(view).querySelector('[data-icon="fake"]')).not.toBeNull();
+        click(triggerOf(view));
+        expect(menuOf(view)).not.toBeNull();
+    });
+    it('DD-16 avatar 트리거는 avatar 이미지를 렌더한다', () => {
+        const view = render(createActionProps({ trigger: { type: 'avatar', avatar: 'me.png' } }));
+        const trigger = triggerOf(view);
+        expect(trigger.classList.contains('ncua-dropdown__trigger--avatar')).toBe(true);
+        expect(trigger.querySelector('.ncua-dropdown__avatar img')?.getAttribute('src')).toBe('me.png');
+        click(trigger);
+        expect(menuOf(view)).not.toBeNull();
+    });
+    it('DD-16 button 트리거는 text 를 렌더한다', () => {
+        const view = render(createActionProps());
+        expect(triggerOf(view).classList.contains('ncua-dropdown__trigger--button')).toBe(true);
+        expect(triggerOf(view).textContent).toBe('더보기');
+    });
+});
+describe('Dropdown 헤더 (DD-17)', () => {
+    const headerOf = (view) => view.querySelector('.ncua-dropdown__header');
+    it('DD-17 avatar 헤더는 avatar·title·subtitle 을 렌더한다', () => {
+        const view = render(createActionProps({
+            opened: true,
+            header: { type: 'avatar', avatar: 'me.png', title: '홍길동', subtitle: '관리자' },
+        }));
+        expect(headerOf(view)?.querySelector('img')?.getAttribute('src')).toBe('me.png');
+        expect(headerOf(view)?.querySelector('.ncua-dropdown__header-title')?.textContent).toBe('홍길동');
+        expect(headerOf(view)?.querySelector('.ncua-dropdown__header-subtitle')?.textContent).toBe('관리자');
+    });
+    it('DD-17 avatar 헤더의 빈 title·subtitle 은 렌더하지 않는다', () => {
+        const view = render(createActionProps({ opened: true, header: { type: 'avatar', avatar: 'me.png', title: '', subtitle: '' } }));
+        expect(headerOf(view)).not.toBeNull();
+        expect(headerOf(view)?.querySelector('.ncua-dropdown__header-title')).toBeNull();
+        expect(headerOf(view)?.querySelector('.ncua-dropdown__header-subtitle')).toBeNull();
+    });
+    it('DD-17 avatar 가 비어 있는 avatar 헤더는 헤더 전체를 렌더하지 않는다', () => {
+        const view = render(createActionProps({ opened: true, header: { type: 'avatar', avatar: '', title: '홍길동', subtitle: '' } }));
+        expect(headerOf(view)).toBeNull();
+    });
+    it('DD-17 text 헤더는 title 을 렌더하고 빈 title 이면 렌더하지 않는다', () => {
+        const view = render(createActionProps({ opened: true, header: { type: 'text', title: '메뉴' } }));
+        expect(headerOf(view)?.querySelector('.ncua-dropdown__header-title')?.textContent).toBe('메뉴');
+        render(createActionProps({ opened: true, header: { type: 'text', title: '' } }));
+        expect(headerOf(view)).toBeNull();
+    });
+    it('DD-17 header 가 없으면 렌더하지 않는다', () => {
+        const view = render(createActionProps({ opened: true }));
+        expect(headerOf(view)).toBeNull();
+    });
+});
+describe('Dropdown action 항목 표현 (DD-18)', () => {
+    it('DD-18 danger · disabled · className · icon · shortcut 을 반영한다', () => {
+        const view = render(createActionProps({
+            opened: true,
+            groups: [
+                {
+                    items: [
+                        { id: 'del', text: '삭제', type: 'danger', className: 'extra', icon: FakeIcon, shortcut: '⌘D' },
+                        { id: 'off', text: '잠김', disabled: true, type: 'default' },
+                    ],
+                },
+            ],
+        }));
+        const danger = actionItemOf(view, '삭제');
+        const off = actionItemOf(view, '잠김');
+        expect(danger.classList.contains('is-danger')).toBe(true);
+        expect(danger.classList.contains('extra')).toBe(true);
+        expect(danger.querySelector('.ncua-dropdown__item-icon[data-icon="fake"]')).not.toBeNull();
+        expect(danger.querySelector('.ncua-dropdown__item-shortcut')?.textContent).toBe('⌘D');
+        expect(off.classList.contains('is-disabled')).toBe(true);
+        expect(off.classList.contains('is-danger')).toBe(false);
+        expect(off.querySelector('.ncua-dropdown__item-icon')).toBeNull();
+        expect(off.querySelector('.ncua-dropdown__item-shortcut')).toBeNull();
+    });
+});
+describe('Dropdown config 항목 표현 (DD-19)', () => {
+    it('DD-19 is-hidden · is-disabled · className · icon 을 반영한다', () => {
+        const { view } = renderConfig(vi.fn(), [
+            {
+                items: [
+                    { id: 'a', text: '숨김', visible: false, className: 'extra', icon: FakeIcon },
+                    { id: 'b', text: '잠김', disabled: true },
+                ],
+            },
+        ]);
+        expect(configItem(view, '숨김').classList.contains('is-hidden')).toBe(true);
+        expect(configItem(view, '숨김').classList.contains('extra')).toBe(true);
+        expect(configItem(view, '숨김').querySelector('.ncua-dropdown__item-icon[data-icon="fake"]')).not.toBeNull();
+        expect(configItem(view, '잠김').classList.contains('is-disabled')).toBe(true);
+        expect(configItem(view, '잠김').classList.contains('is-hidden')).toBe(false);
+        expect(configItem(view, '잠김').querySelector('.ncua-dropdown__item-icon')).toBeNull();
+    });
+    it('DD-19 sortable 이 아닌 그룹은 드래그 핸들이 없다', () => {
+        const { view } = renderConfig(vi.fn(), [{ items: [{ id: 'a', text: '주문번호', visible: true }] }]);
+        expect(configItem(view, '주문번호').querySelector('.ncua-dropdown__item-drag-handle')).toBeNull();
+    });
+    it('DD-19 노출 토글 아이콘은 노출 시 Eye, 숨김 시 EyeOff 로 바뀐다', () => {
+        const { view } = renderConfig();
+        const toggle = configItem(view, '주문번호').querySelector('.ncua-dropdown__item-visibility');
+        expect(toggle?.innerHTML).toBe(iconMarkupOf(Eye));
+        click(toggle);
+        expect(toggle?.innerHTML).toBe(iconMarkupOf(EyeOff));
+    });
+});
+describe('Dropdown 정렬·className·적용 버튼 텍스트 (DD-20·21)', () => {
+    it('DD-20 align=right 면 --right 클래스를, className 을 루트에 붙인다', () => {
+        const view = render(createActionProps({ align: 'right', className: 'custom' }));
+        expect(view.firstElementChild?.classList.contains('ncua-dropdown--right')).toBe(true);
+        expect(view.firstElementChild?.classList.contains('custom')).toBe(true);
+    });
+    it('DD-20 기본(left)에서는 --right 클래스가 없다', () => {
+        const view = render(createActionProps());
+        expect(view.firstElementChild?.classList.contains('ncua-dropdown')).toBe(true);
+        expect(view.firstElementChild?.classList.contains('ncua-dropdown--right')).toBe(false);
+    });
+    it('DD-21 applyButtonText 미지정 시 "설정 완료", 지정 시 그 텍스트를 쓴다', () => {
+        const view = render(createConfigProps({ opened: true }));
+        expect(applyButtonOf(view).textContent).toBe('설정 완료');
+        render(createConfigProps({ opened: true, applyButtonText: '저장' }));
+        expect(applyButtonOf(view).textContent).toBe('저장');
+    });
+    it('DD-21 action 메뉴에는 footer 가 없다', () => {
+        const view = render(createActionProps({ opened: true }));
+        expect(view.querySelector('.ncua-dropdown__footer')).toBeNull();
+    });
+});
+// ── P3 ──────────────────────────────────────────────────
+describe('Dropdown 그룹 key (DD-22)', () => {
+    it('DD-22 그룹 key 는 첫 항목 id 라 그룹 순서를 바꿔 다시 렌더하면 그룹 DOM 노드가 따라 이동한다', () => {
+        // key 경고 유무는 React 가 컴포넌트별로 한 번만 찍어 실행 순서에 따라 달라지므로 노드 재사용으로 key 를 확인한다
+        const groupA = { items: [{ id: 'a', text: '가' }] };
+        const groupB = { items: [{ id: 'b', text: '나' }] };
+        const view = render(createActionProps({ opened: true, groups: [groupA, groupB] }));
+        const [nodeA, nodeB] = Array.from(view.querySelectorAll('.ncua-dropdown__group'));
+        render(createActionProps({ opened: true, groups: [groupB, groupA] }));
+        const [first, second] = Array.from(view.querySelectorAll('.ncua-dropdown__group'));
+        expect(first).toBe(nodeB);
+        expect(second).toBe(nodeA);
+    });
+    it('DD-22 빈 그룹이 둘 이상이어도(key 가 undefined 로 겹침) 그룹 2개를 렌더한다', () => {
+        // 현재 동작 고정 — 결함 후보: #588 (그룹 key = 첫 항목 id 라 빈 그룹끼리 key 가 겹침)
+        // React key 경고는 전역에서 한 번만 찍혀 실행 순서에 따라 달라지므로 단언하지 않고 소음만 막는다
+        vi.spyOn(console, 'error').mockImplementation(() => undefined);
+        const view = render(createActionProps({ opened: true, groups: [{ items: [] }, { items: [] }] }));
+        expect(view.querySelectorAll('.ncua-dropdown__group')).toHaveLength(2);
+    });
+    it('DD-22 서로 다른 그룹의 첫 항목 id 가 같아도(key 충돌) 두 그룹의 항목을 모두 렌더한다', () => {
+        // 현재 동작 고정 — 결함 후보: #588 (그룹 key = 첫 항목 id 라 첫 id 가 같으면 key 충돌)
+        vi.spyOn(console, 'error').mockImplementation(() => undefined);
+        const view = render(createActionProps({
+            opened: true,
+            groups: [{ items: [{ id: 'dup', text: '가' }] }, { items: [{ id: 'dup', text: '나' }] }],
+        }));
+        expect(view.querySelectorAll('.ncua-dropdown__group')).toHaveLength(2);
+        expect(Array.from(view.querySelectorAll('.ncua-dropdown__group .ncua-dropdown__item-text')).map((element) => element.textContent)).toEqual(['가', '나']);
+    });
+    it.todo('DD-22 그룹 key 는 빈 그룹·첫 항목 id 중복과 무관하게 그룹마다 고유해야 한다');
+});
+describe('Dropdown config disabled 항목 (DD-23)', () => {
+    const disabledGroups = () => [
+        {
+            sortable: true,
+            items: [
+                { id: 'a', text: '주문번호', visible: true, disabled: true },
+                { id: 'b', text: '상품명', visible: true },
+            ],
+        },
+    ];
+    it('DD-23 disabled 항목도 노출 토글과 방향키 이동이 그대로 동작한다 (is-disabled 는 시각 표시뿐)', () => {
+        // 현재 동작 고정 — 결함 후보: #588 (config disabled 가 클래스만 붙이고 토글·이동 핸들러를 막지 않음)
+        const { view, onApply, groups } = renderConfig(vi.fn(), disabledGroups());
+        const item = configItem(view, '주문번호');
+        expect(item.classList.contains('is-disabled')).toBe(true);
+        click(item.querySelector('.ncua-dropdown__item-visibility'));
+        keyDown(item.querySelector('.ncua-dropdown__item-drag-handle'), 'ArrowDown');
+        click(applyButtonOf(view));
+        expect(onApply).toHaveBeenCalledWith([groups[0].items[1], { ...groups[0].items[0], visible: false }]);
+    });
+    it.todo('DD-23 config disabled 항목은 노출 토글·순서 이동이 막혀야 한다');
+});