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

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

@@ -0,0 +1,1017 @@
+// @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(/*#__PURE__*/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 = function () {
+  let onApply = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : vi.fn();
+  let groups = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 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 = function () {
+  let scope = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : document;
+  return 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 = _ref => {
+  let {
+    className
+  } = _ref;
+  return /*#__PURE__*/createElement('svg', {
+    className,
+    'data-icon': 'fake'
+  });
+};
+/** 아이콘 컴포넌트를 따로 렌더한 마크업 — 단언 전에 언마운트까지 끝내 루트가 남지 않는다. */
+const iconMarkupOf = icon => {
+  const host = document.createElement('div');
+  const iconRoot = createRoot(host);
+  try {
+    act(() => {
+      iconRoot.render(/*#__PURE__*/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 = function () {
+  let overrides = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  return {
+    trigger: {
+      type: 'button',
+      text: '더보기'
+    },
+    groups: [{
+      items: [{
+        id: 'edit',
+        text: '수정',
+        onClick: vi.fn()
+      }]
+    }],
+    ...overrides
+  };
+};
+const createConfigProps = function () {
+  let overrides = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  return {
+    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(_ref2 => {
+      let [type] = _ref2;
+      return 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(/*#__PURE__*/createElement(FloatingProvider, {
+        value: {
+          preferPortal: true,
+          portalContainer
+        }
+      }, /*#__PURE__*/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(/*#__PURE__*/createElement(FloatingProvider, {
+        value: {
+          preferPortal: true
+        }
+      }, /*#__PURE__*/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: /*#__PURE__*/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 항목은 노출 토글·순서 이동이 막혀야 한다');
+});