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

package/dist/temp/src/components/data-display/data-grid/__tests__/DataGrid.test.js

@@ -0,0 +1,291 @@
+// @vitest-environment jsdom
+//
+// DataGrid (React) 위험 경로 — 위험 목록표 DG-xx.
+// Table·하위 컴포넌트는 실제 구현을 쓴다 — DataGrid.Table 로 넘긴 프롭이 Table 결과 DOM 에 반영되는지가 검증 대상.
+// fixedHeader·horizontalScroll 은 Table 의 스크롤바 훅이 ResizeObserver 를 쓰므로 stub 을 설치한다.
+import { createElement, createRef, Fragment } from 'react';
+import { createRoot } from 'react-dom/client';
+import { act } from 'react-dom/test-utils';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { Table } from '../../table';
+import { TABLE_HEADER_HEIGHT } from '../../table/useTableScrollbars';
+import { DataGrid } from '../DataGrid';
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+const MAX_HEIGHT = 240;
+const MIN_WIDTH = 1600;
+class ResizeObserverStub {
+    observe() {
+        // 스크롤바 수치는 useTableScrollbars 테스트가 검증한다.
+    }
+    unobserve() {
+        // 사용하지 않는다.
+    }
+    disconnect() {
+        // 사용하지 않는다.
+    }
+}
+let root = null;
+let container = null;
+beforeEach(() => {
+    vi.stubGlobal('ResizeObserver', ResizeObserverStub);
+});
+afterEach(() => {
+    if (root) {
+        act(() => {
+            root?.unmount();
+        });
+    }
+    root = null;
+    container = null;
+    document.body.innerHTML = '';
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+});
+const render = (props, ...children) => {
+    if (!container) {
+        container = document.createElement('div');
+        document.body.appendChild(container);
+        root = createRoot(container);
+    }
+    act(() => {
+        root?.render(createElement(DataGrid, props, ...children));
+    });
+    return container.firstElementChild;
+};
+const tableBody = () => createElement(Table.Body, null, createElement(Table.Row, null, createElement(Table.Cell, null, '주문번호'), createElement(Table.Cell, null, '상태')));
+const dataTable = (props = {}) => createElement(DataGrid.Table, props, tableBody());
+const actionBar = (props, label) => createElement(DataGrid.ActionBar, props, label);
+/** 요소의 클래스 중 data-grid 슬롯을 나타내는 첫 클래스 */
+const slotOf = (element) => Array.from(element.classList).find((name) => name.startsWith('ncua-data-grid__')) ?? element.className;
+const childSlots = (element) => Array.from(element?.children ?? []).map(slotOf);
+const tableWrapperOf = (grid) => grid.querySelector('.ncua-data-grid__table-wrapper');
+const ncuaTableOf = (grid) => grid.querySelector('.ncua-table');
+const hasClass = (element, className) => element?.classList.contains(className) ?? false;
+const actionBars = (grid) => Array.from(grid.querySelectorAll('.ncua-data-grid__action-bar'));
+describe('DataGrid — 자식 분류·배치 (DG-01)', () => {
+    it('DG-01 입력 순서와 무관하게 SearchFilter → Summary → table-wrapper → Pagination 순으로 배치한다', () => {
+        const grid = render({}, createElement(DataGrid.Pagination, null, '페이지'), actionBar({ position: 'bottom' }, '하단'), dataTable(), actionBar({}, '상단'), createElement(DataGrid.FilterBar, null, '필터'), createElement(DataGrid.Summary, null, '요약'), createElement(DataGrid.SearchFilter, null, '검색'));
+        expect(childSlots(grid)).toEqual([
+            'ncua-data-grid__search-filter',
+            'ncua-data-grid__summary',
+            'ncua-data-grid__table-wrapper',
+            'ncua-data-grid__pagination',
+        ]);
+    });
+    it('DG-01 table-wrapper 안은 FilterBar → 상단 ActionBar → Table → 하단 ActionBar 순이다', () => {
+        const grid = render({}, actionBar({ position: 'bottom' }, '하단'), dataTable(), actionBar({ position: 'top' }, '상단'), createElement(DataGrid.FilterBar, null, '필터'));
+        const wrapperChildren = Array.from(tableWrapperOf(grid)?.children ?? []);
+        expect(wrapperChildren.map(slotOf)).toEqual([
+            'ncua-data-grid__filter-bar',
+            'ncua-data-grid__action-bar',
+            'ncua-data-grid__table',
+            'ncua-data-grid__action-bar',
+        ]);
+        expect(wrapperChildren[1].textContent).toBe('상단');
+        expect(wrapperChildren[3].textContent).toBe('하단');
+    });
+    it('DG-01 같은 슬롯이 여러 개면 입력 순서를 유지한다', () => {
+        const grid = render({}, createElement(DataGrid.Summary, null, '요약 1'), createElement(DataGrid.SearchFilter, null, '검색'), createElement(DataGrid.Summary, null, '요약 2'));
+        const summaries = Array.from(grid.querySelectorAll('.ncua-data-grid__summary'));
+        expect(summaries.map((summary) => summary.textContent)).toEqual(['요약 1', '요약 2']);
+        expect(grid.firstElementChild?.textContent).toBe('검색');
+    });
+    it('DG-01 정적 인자로 넘긴 자식을 재배치해도 React key 경고가 나지 않는다', () => {
+        const consoleError = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+        render({}, createElement(DataGrid.Pagination, null, '페이지'), dataTable(), createElement(DataGrid.Summary, null, '요약 1'), createElement(DataGrid.Summary, null, '요약 2'));
+        expect(consoleError).not.toHaveBeenCalled();
+    });
+});
+describe('DataGrid.Table — Table 로 프롭 전달 (DG-02)', () => {
+    it('DG-02 기본은 horizontal·hoverable 이고 Table 에 ncua-table--in-data-grid 를 붙인다', () => {
+        const table = ncuaTableOf(render({}, dataTable()));
+        expect(hasClass(table, 'ncua-table--in-data-grid')).toBe(true);
+        expect(hasClass(table, 'ncua-table--horizontal')).toBe(true);
+        expect(hasClass(table, 'ncua-table--hoverable')).toBe(true);
+        expect(hasClass(table, 'ncua-table--fixed-header')).toBe(false);
+        expect(hasClass(table, 'ncua-table--selectable')).toBe(false);
+        expect(hasClass(table, 'ncua-table--draggable')).toBe(false);
+        expect(table.querySelector('td')?.textContent).toBe('주문번호');
+    });
+    it('DG-02 type vertical 을 전달한다', () => {
+        const table = ncuaTableOf(render({}, dataTable({ type: 'vertical' })));
+        expect(hasClass(table, 'ncua-table--vertical')).toBe(true);
+        expect(hasClass(table, 'ncua-table--horizontal')).toBe(false);
+    });
+    it('DG-02 fixedHeader 와 maxHeight 를 전달해 스크롤 영역 최대 높이에 헤더 높이를 더한다', () => {
+        const grid = render({}, dataTable({ fixedHeader: true, maxHeight: MAX_HEIGHT }));
+        const scrollContainer = grid.querySelector('.ncua-table__scroll-container');
+        expect(hasClass(ncuaTableOf(grid), 'ncua-table--fixed-header')).toBe(true);
+        expect(scrollContainer?.style.maxHeight).toBe(`${MAX_HEIGHT + TABLE_HEADER_HEIGHT}px`);
+    });
+    it('DG-02 hoverable false 를 전달한다', () => {
+        const table = ncuaTableOf(render({}, dataTable({ hoverable: false })));
+        expect(hasClass(table, 'ncua-table--hoverable')).toBe(false);
+    });
+    it('DG-02 selectable 을 전달한다', () => {
+        const table = ncuaTableOf(render({}, dataTable({ selectable: true })));
+        expect(hasClass(table, 'ncua-table--selectable')).toBe(true);
+    });
+    it('DG-02 horizontalScroll 과 minWidth 를 전달해 가로 스크롤 컨테이너와 최소 폭 변수를 만든다', () => {
+        const grid = render({}, dataTable({ horizontalScroll: true, minWidth: MIN_WIDTH }));
+        const inner = grid.querySelector('.ncua-table__h-scroll-inner');
+        expect(grid.querySelector('.ncua-table__h-scroll-container')).not.toBeNull();
+        expect(inner?.style.getPropertyValue('--ncua-table-min-width')).toBe(`${MIN_WIDTH}px`);
+    });
+    it('DG-02 draggable 을 전달한다', () => {
+        const table = ncuaTableOf(render({}, dataTable({ draggable: true })));
+        expect(hasClass(table, 'ncua-table--draggable')).toBe(true);
+    });
+    it('DG-02 className 은 wrapper div 에 붙고 ref 는 그 wrapper div 를 가리킨다', () => {
+        const ref = createRef();
+        const grid = render({}, createElement(DataGrid.Table, { className: 'order-table', ref }, tableBody()));
+        const wrapper = grid.querySelector('.ncua-data-grid__table');
+        expect(hasClass(wrapper, 'order-table')).toBe(true);
+        expect(hasClass(ncuaTableOf(grid), 'order-table')).toBe(false);
+        expect(ref.current).toBe(wrapper);
+    });
+});
+describe('DataGrid — ActionBar 위치·표시 (DG-03)', () => {
+    it('DG-03 position 을 생략한 ActionBar 는 상단 슬롯(Table 앞)에 --top 으로 놓인다', () => {
+        const grid = render({}, dataTable(), actionBar({}, '상단'));
+        const [bar] = actionBars(grid);
+        expect(hasClass(bar, 'ncua-data-grid__action-bar--top')).toBe(true);
+        expect(bar.nextElementSibling).toBe(grid.querySelector('.ncua-data-grid__table'));
+    });
+    it('DG-03 position bottom 인 ActionBar 는 Table 뒤에 --bottom 으로 놓인다', () => {
+        const grid = render({}, actionBar({ position: 'bottom' }, '하단'), dataTable());
+        const [bar] = actionBars(grid);
+        expect(hasClass(bar, 'ncua-data-grid__action-bar--bottom')).toBe(true);
+        expect(bar.previousElementSibling).toBe(grid.querySelector('.ncua-data-grid__table'));
+    });
+    it('DG-03 showActionBar false 면 상단·하단 ActionBar 를 모두 숨긴다', () => {
+        const grid = render({ showActionBar: false }, actionBar({}, '상단'), dataTable(), actionBar({ position: 'bottom' }, '하단'));
+        expect(actionBars(grid)).toHaveLength(0);
+        expect(grid.querySelector('.ncua-data-grid__table')).not.toBeNull();
+    });
+    it('DG-03 showActionBar true 면 생략과 같이 ActionBar 를 표시한다', () => {
+        const grid = render({ showActionBar: true }, actionBar({}, '상단'), dataTable(), actionBar({ position: 'bottom' }, '하단'));
+        expect(actionBars(grid).map((bar) => bar.textContent)).toEqual(['상단', '하단']);
+    });
+});
+describe('DataGrid — 빈 하단 바 (DG-04)', () => {
+    const emptyBottomBar = (grid) => {
+        const last = tableWrapperOf(grid)?.lastElementChild ?? null;
+        return hasClass(last, 'ncua-data-grid__action-bar--bottom') && last?.childNodes.length === 0 ? last : null;
+    };
+    it('DG-04 하단 ActionBar 없이 selectable Table 이면 빈 --bottom 바를 wrapper 끝에 둔다', () => {
+        const grid = render({}, dataTable({ selectable: true }));
+        expect(emptyBottomBar(grid)).not.toBeNull();
+        expect(hasClass(emptyBottomBar(grid), 'ncua-data-grid__action-bar')).toBe(true);
+    });
+    it('DG-04 하단 ActionBar 가 있으면 빈 바를 추가하지 않는다', () => {
+        const grid = render({}, dataTable({ selectable: true }), actionBar({ position: 'bottom' }, '하단'));
+        expect(grid.querySelectorAll('.ncua-data-grid__action-bar--bottom')).toHaveLength(1);
+        expect(emptyBottomBar(grid)).toBeNull();
+    });
+    it('DG-04 showActionBar false 면 selectable 이어도 빈 바를 두지 않는다', () => {
+        const grid = render({ showActionBar: false }, dataTable({ selectable: true }));
+        expect(grid.querySelector('.ncua-data-grid__action-bar--bottom')).toBeNull();
+    });
+    it.each([
+        ['생략', {}],
+        ['false', { selectable: false }],
+    ])('DG-04 selectable 이 %s 면 빈 바를 두지 않는다', (_label, tableProps) => {
+        const grid = render({}, dataTable(tableProps));
+        expect(grid.querySelector('.ncua-data-grid__action-bar--bottom')).toBeNull();
+    });
+});
+describe('DataGrid — 루트 (DG-05)', () => {
+    it('DG-05 variant 기본값은 search-result 이고 className 을 함께 붙인다', () => {
+        const grid = render({ className: 'order-grid' }, dataTable());
+        expect(hasClass(grid, 'ncua-data-grid')).toBe(true);
+        expect(hasClass(grid, 'ncua-data-grid--search-result')).toBe(true);
+        expect(hasClass(grid, 'order-grid')).toBe(true);
+    });
+    it('DG-05 variant horizontal 이면 --horizontal modifier 를 붙인다', () => {
+        const grid = render({ variant: 'horizontal' }, dataTable());
+        expect(hasClass(grid, 'ncua-data-grid--horizontal')).toBe(true);
+        expect(hasClass(grid, 'ncua-data-grid--search-result')).toBe(false);
+    });
+    it('DG-05 나머지 속성(aria·data)을 루트에 전달하고 ref 는 루트 div 를 가리킨다', () => {
+        const ref = createRef();
+        const grid = render({ 'aria-label': '주문 목록', 'data-testid': 'grid', ref }, dataTable());
+        expect(grid.getAttribute('aria-label')).toBe('주문 목록');
+        expect(grid.dataset.testid).toBe('grid');
+        expect(ref.current).toBe(grid);
+    });
+});
+describe('DataGrid — table-wrapper 유무 (DG-06)', () => {
+    it('DG-06 SearchFilter·Summary·Pagination 만 있으면 table-wrapper 를 만들지 않는다', () => {
+        const grid = render({}, createElement(DataGrid.SearchFilter, null, '검색'), createElement(DataGrid.Summary, null, '요약'), createElement(DataGrid.Pagination, null, '페이지'));
+        expect(tableWrapperOf(grid)).toBeNull();
+    });
+    it('DG-06 showActionBar false 에 ActionBar 만 있으면 table-wrapper 를 만들지 않는다', () => {
+        const grid = render({ showActionBar: false }, actionBar({}, '상단'), actionBar({ position: 'bottom' }, '하단'));
+        expect(tableWrapperOf(grid)).toBeNull();
+    });
+    it('DG-06 하단 ActionBar 만 있어도 표시 중이면 table-wrapper 를 만든다', () => {
+        const grid = render({}, actionBar({ position: 'bottom' }, '하단'));
+        expect(childSlots(tableWrapperOf(grid))).toEqual(['ncua-data-grid__action-bar']);
+    });
+    it('DG-06 FilterBar 만 있어도 table-wrapper 를 만든다', () => {
+        const grid = render({}, createElement(DataGrid.FilterBar, null, '필터'));
+        expect(childSlots(tableWrapperOf(grid))).toEqual(['ncua-data-grid__filter-bar']);
+    });
+});
+describe('DataGrid — 하위 컴포넌트 (DG-07)', () => {
+    it.each([
+        ['SearchFilter', DataGrid.SearchFilter, 'ncua-data-grid__search-filter'],
+        ['Summary', DataGrid.Summary, 'ncua-data-grid__summary'],
+        ['FilterBar', DataGrid.FilterBar, 'ncua-data-grid__filter-bar'],
+        ['Pagination', DataGrid.Pagination, 'ncua-data-grid__pagination'],
+    ])('DG-07 %s 는 기본 클래스·className·나머지 속성을 렌더한다', (_name, Component, baseClass) => {
+        const slotProps = { className: 'custom', 'data-slot': 'x', children: '내용' };
+        const grid = render({}, createElement(Component, slotProps));
+        const element = grid.querySelector(`.${baseClass}`);
+        expect(hasClass(element, 'custom')).toBe(true);
+        expect(element?.dataset.slot).toBe('x');
+        expect(element?.textContent).toBe('내용');
+    });
+    it('DG-07 ActionBar 는 className·나머지 속성을 렌더한다', () => {
+        const slotProps = { className: 'custom', 'data-slot': 'x', children: '상단' };
+        const [bar] = actionBars(render({}, createElement(DataGrid.ActionBar, slotProps)));
+        expect(hasClass(bar, 'custom')).toBe(true);
+        expect(bar.dataset.slot).toBe('x');
+    });
+    it('DG-07 ActionBar align 기본값은 space-between 이다', () => {
+        const [bar] = actionBars(render({}, actionBar({}, '상단')));
+        expect(hasClass(bar, 'ncua-data-grid__action-bar--space-between')).toBe(true);
+        expect(hasClass(bar, 'ncua-data-grid__action-bar--left')).toBe(false);
+    });
+    it.each([
+        ['left', 'ncua-data-grid__action-bar--left'],
+        ['right', 'ncua-data-grid__action-bar--right'],
+    ])('DG-07 ActionBar align %s 면 해당 modifier 만 붙인다', (align, modifier) => {
+        const [bar] = actionBars(render({}, actionBar({ align }, '상단')));
+        expect(hasClass(bar, modifier)).toBe(true);
+        expect(hasClass(bar, 'ncua-data-grid__action-bar--space-between')).toBe(false);
+    });
+});
+describe('DataGrid — 슬롯이 아닌 자식 (DG-08)', () => {
+    const SummaryWrapper = () => createElement(DataGrid.Summary, null, '래퍼 요약');
+    it('DG-08 Fragment·사용자 래퍼·슬롯 아닌 요소·텍스트는 경고 없이 버려진다', () => {
+        // 현재 동작 고정 — 결함 후보: #593 (Children.forEach 가 Fragment 를 펼치지 않고 맵에 없는 타입은 무시)
+        const consoleError = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+        const consoleWarn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+        const grid = render({}, createElement(Fragment, null, createElement(DataGrid.Summary, null, 'Fragment 요약')), createElement(SummaryWrapper), createElement('div', { className: 'custom-slot' }, '임의 div'), '텍스트', dataTable());
+        expect(grid.querySelector('.ncua-data-grid__summary')).toBeNull();
+        expect(grid.querySelector('.custom-slot')).toBeNull();
+        expect(grid.textContent).not.toContain('텍스트');
+        expect(childSlots(grid)).toEqual(['ncua-data-grid__table-wrapper']);
+        expect(consoleError).not.toHaveBeenCalled();
+        expect(consoleWarn).not.toHaveBeenCalled();
+    });
+    it.todo('DG-08 Fragment 로 감싼 슬롯은 펼쳐 배치하고, 비슬롯 자식은 dev 경고하거나 Table 처럼 유지한다 (정책은 #593 에서 결정)');
+});
+describe('DataGrid — 조건부 렌더 자식 (DG-09)', () => {
+    it('DG-09 null·false·undefined 자식은 무시하고 예외 없이 나머지를 배치한다', () => {
+        const grid = render({}, null, false, undefined, createElement(DataGrid.Summary, null, '요약'), dataTable());
+        expect(childSlots(grid)).toEqual(['ncua-data-grid__summary', 'ncua-data-grid__table-wrapper']);
+    });
+});

package/dist/temp/src/components/data-display/table/__tests__/Table.dnd.dragCell.test.d.ts

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

package/dist/temp/src/components/data-display/table/__tests__/Table.dnd.dragCell.test.js

@@ -0,0 +1,255 @@
+// @vitest-environment jsdom
+//
+// Table 행 드래그앤드롭 위험 경로 중 drag 쪽(DragCell 핸들 · 드래그 상태 · 프리뷰 · 자동 스크롤) — 위험 목록표 TB-xx (DnD).
+// adapter mock 방식은 Table.dnd.test.ts 머리 주석과 같다. 프리뷰 오버레이 좌표는 행의 getBoundingClientRect stub 으로 만든다.
+import { disableNativeDragPreview } from '@atlaskit/pragmatic-drag-and-drop/element/disable-native-drag-preview';
+import { autoScrollForElements } from '@atlaskit/pragmatic-drag-and-drop-auto-scroll/element';
+import { createElement } from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { Table } from '../Table';
+import { cleanupDragPreview, customTable, draggableArgsOf, draggables, draggableTable, endDrag, fireDragOver, generatePreview, MOVE_X, MOVE_Y, OFFSET_X, OFFSET_Y, previewOverlays, ROW_HEIGHT, ROW_IDS, ROW_LEFT, ROW_TOP, ROW_WIDTH, rowOf, START_X, START_Y, sourceDataOf, startDrag, stubRect, trackDragOverListeners, } from './tableDndTestUtils';
+import { cleanupRender, ResizeObserverStub, render } from './tableTestUtils';
+// 등록 기록은 tableDndTestUtils 의 draggables·dropTargets·monitors 가 mock 호출 이력에서 읽는다.
+vi.mock('@atlaskit/pragmatic-drag-and-drop/element/adapter', () => ({
+    draggable: vi.fn(() => vi.fn()),
+    dropTargetForElements: vi.fn(() => vi.fn()),
+    monitorForElements: vi.fn(() => vi.fn()),
+}));
+// 네이티브 프리뷰 비활성화·자동 스크롤은 브라우저 drag 세션이 있어야 의미가 있으므로 호출 여부만 본다.
+vi.mock('@atlaskit/pragmatic-drag-and-drop/element/disable-native-drag-preview', () => ({
+    disableNativeDragPreview: vi.fn(),
+}));
+const autoScrollCleanup = vi.hoisted(() => ({ calls: 0 }));
+vi.mock('@atlaskit/pragmatic-drag-and-drop-auto-scroll/element', () => ({
+    autoScrollForElements: vi.fn(() => () => {
+        autoScrollCleanup.calls += 1;
+    }),
+}));
+beforeEach(() => {
+    vi.stubGlobal('ResizeObserver', ResizeObserverStub);
+    autoScrollCleanup.calls = 0;
+    trackDragOverListeners();
+});
+afterEach(() => {
+    cleanupRender();
+    cleanupDragPreview();
+    vi.clearAllMocks();
+    vi.unstubAllGlobals();
+});
+describe('Table.DragCell 핸들 등록 (TB-08)', () => {
+    it('TB-08 draggable 테이블이면 핸들 button 을 렌더하고 draggable 로 등록한다', () => {
+        const view = render(draggableTable(vi.fn()));
+        const handle = rowOf('a').querySelector('button.ncua-table__drag-handle');
+        expect(handle.type).toBe('button');
+        expect(handle.getAttribute('aria-label')).toBe('행 순서 변경');
+        expect(handle.disabled).toBe(false);
+        expect(handle.querySelector('svg')).not.toBeNull();
+        expect(draggableArgsOf('a').element).toBe(handle);
+        expect(view.querySelectorAll('button.ncua-table__drag-handle')).toHaveLength(ROW_IDS.length);
+    });
+    it('TB-08 getInitialData 는 {id: dragId, tableId} 를 돌려준다', () => {
+        render(draggableTable(vi.fn()));
+        const tableId = sourceDataOf('b').tableId;
+        expect(draggableArgsOf('a').getInitialData?.({})).toEqual({ id: 'a', tableId });
+    });
+    it('TB-08 disabled 면 button 을 disabled 로 렌더하고 draggable 로 등록하지 않는다', () => {
+        render(customTable([{ id: 'a' }, { id: 'b', disabled: true }]));
+        const handle = rowOf('b').querySelector('button');
+        expect(handle.disabled).toBe(true);
+        expect(draggables().map((entry) => entry.element)).not.toContain(handle);
+        expect(draggables()).toHaveLength(1);
+    });
+    it('TB-08 draggable 이 아니면 핸들 없이 children 만 렌더한다', () => {
+        const view = render(createElement(Table, null, createElement(Table.Body, null, createElement(Table.Row, { dragId: 'a' }, createElement(Table.DragCell, { className: 'dc-extra' }, '체크')))));
+        const cell = view.querySelector('td.ncua-table__drag-cell');
+        expect(cell.classList.contains('dc-extra')).toBe(true);
+        expect(cell.querySelector('button')).toBeNull();
+        expect(cell.querySelector('.ncua-table__drag-cell-inner')?.textContent).toBe('체크');
+    });
+    it('TB-08 dragId 가 없는 행의 DragCell 은 핸들은 그리지만 draggable 로 등록하지 않는다', () => {
+        // 현재 동작 고정 — 결함 후보: #588 (끌 수 없는 핸들이 활성 상태로 보여 사용자가 조작 가능하다고 오인)
+        render(customTable([{ id: '' }]));
+        expect(document.querySelector('button.ncua-table__drag-handle')).not.toBeNull();
+        expect(draggables()).toHaveLength(0);
+    });
+    it.todo('TB-08 dragId 가 없는 행의 DragCell 은 핸들을 그리지 않거나 비활성(disabled)으로 표시한다');
+});
+describe('Table.DragCell 드래그 상태 (TB-09)', () => {
+    it('TB-09 onDragStart 이면 행에 is-dragging 을 붙이고 onDrop 이면 뗀다', () => {
+        render(draggableTable(vi.fn()));
+        const args = draggableArgsOf('b');
+        startDrag(args);
+        expect(rowOf('b').classList.contains('is-dragging')).toBe(true);
+        expect(rowOf('a').classList.contains('is-dragging')).toBe(false);
+        endDrag(args);
+        expect(rowOf('b').classList.contains('is-dragging')).toBe(false);
+    });
+});
+describe('Table.DragCell 드래그 프리뷰 (TB-10)', () => {
+    const stubRowRect = (dragId) => {
+        stubRect(rowOf(dragId), { left: ROW_LEFT, top: ROW_TOP, width: ROW_WIDTH, height: ROW_HEIGHT });
+    };
+    it('TB-10 onGenerateDragPreview 는 네이티브 프리뷰를 끄고 body 에는 아직 아무것도 붙이지 않는다', () => {
+        render(draggableTable(vi.fn()));
+        stubRowRect('a');
+        const nativeSetDragImage = vi.fn();
+        generatePreview(draggableArgsOf('a'), nativeSetDragImage);
+        expect(disableNativeDragPreview).toHaveBeenCalledWith({ nativeSetDragImage });
+        expect(previewOverlays()).toHaveLength(0);
+    });
+    it('TB-10 onDragStart 에 오버레이를 body 에 붙이고 포인터-행 오프셋(+배지 절반)만큼 당긴 좌표에 둔다', () => {
+        render(draggableTable(vi.fn()));
+        stubRowRect('a');
+        const args = draggableArgsOf('a');
+        generatePreview(args);
+        startDrag(args);
+        const [overlay] = previewOverlays();
+        expect(previewOverlays()).toHaveLength(1);
+        expect(overlay.style.left).toBe(`${START_X - OFFSET_X}px`);
+        expect(overlay.style.top).toBe(`${START_Y - OFFSET_Y}px`);
+        expect(overlay.querySelector('.ncua-table-dnd-preview__badge')).toBeNull();
+        expect(overlay.querySelectorAll('.ncua-table-dnd-preview__card')).toHaveLength(1);
+    });
+    it('TB-10 dragover 마다 오버레이가 포인터를 따라가고 onDrop 이면 제거·리스너 해제한다', () => {
+        render(draggableTable(vi.fn()));
+        stubRowRect('a');
+        const args = draggableArgsOf('a');
+        generatePreview(args);
+        startDrag(args);
+        const [overlay] = previewOverlays();
+        const dragOverHandler = vi
+            .mocked(document.addEventListener)
+            .mock.calls.filter(([type]) => type === 'dragover')
+            .pop()?.[1];
+        expect(dragOverHandler).toBeDefined();
+        fireDragOver(MOVE_X, MOVE_Y);
+        expect(overlay.style.left).toBe(`${MOVE_X - OFFSET_X}px`);
+        expect(overlay.style.top).toBe(`${MOVE_Y - OFFSET_Y}px`);
+        const removeSpy = vi.spyOn(document, 'removeEventListener');
+        try {
+            endDrag(args);
+            expect(previewOverlays()).toHaveLength(0);
+            expect(overlay.isConnected).toBe(false);
+            // onDrop 이 overlay 를 먼저 비워 onDragOver 가 일찍 빠지므로, 좌표 불변만으로는 리스너 해제를 증명할 수 없다
+            expect(removeSpy).toHaveBeenCalledWith('dragover', dragOverHandler);
+        }
+        finally {
+            removeSpy.mockRestore();
+        }
+    });
+    it('TB-10 onDrop 뒤 다음 드래그는 프리뷰 생성 없이 onDragStart 만 와도 오버레이를 만들지 않는다 (pendingPreview 초기화)', () => {
+        render(draggableTable(vi.fn()));
+        stubRowRect('a');
+        const args = draggableArgsOf('a');
+        generatePreview(args);
+        startDrag(args);
+        endDrag(args);
+        startDrag(args);
+        expect(previewOverlays()).toHaveLength(0);
+        endDrag(args);
+    });
+    it('TB-10 선택된 행을 끌면 같은 body 의 선택 행 전부로 프리뷰를 만들고 개수 배지를 붙인다', () => {
+        render(customTable([{ id: 'a', selected: true }, { id: 'b' }, { id: 'c', selected: true }]));
+        stubRowRect('a');
+        const args = draggableArgsOf('a');
+        generatePreview(args);
+        startDrag(args);
+        const [overlay] = previewOverlays();
+        expect(overlay.querySelector('.ncua-table-dnd-preview__badge')?.textContent).toBe('2');
+        expect(overlay.querySelectorAll('.ncua-table-dnd-preview__card')).toHaveLength(2);
+        endDrag(args);
+    });
+    it('TB-10 선택된 행이 하나뿐이면 단일 행 프리뷰다', () => {
+        render(customTable([{ id: 'a', selected: true }, { id: 'b' }]));
+        stubRowRect('a');
+        const args = draggableArgsOf('a');
+        generatePreview(args);
+        startDrag(args);
+        expect(previewOverlays()[0].querySelector('.ncua-table-dnd-preview__badge')).toBeNull();
+        endDrag(args);
+    });
+    it('TB-10 선택되지 않은 행을 끌면 다른 선택 행이 있어도 그 행만 프리뷰한다', () => {
+        render(customTable([{ id: 'a' }, { id: 'b', selected: true }, { id: 'c', selected: true }]));
+        stubRowRect('a');
+        const args = draggableArgsOf('a');
+        generatePreview(args);
+        startDrag(args);
+        expect(previewOverlays()[0].querySelectorAll('.ncua-table-dnd-preview__card')).toHaveLength(1);
+        endDrag(args);
+    });
+    it('TB-10 Table.Body 가 아닌 tbody 안의 선택 행이면 body 를 못 찾아 단일 행 프리뷰다', () => {
+        render(createElement(Table, { draggable: true }, createElement('tbody', null, ['a', 'b'].map((id) => createElement(Table.Row, { key: id, dragId: id, selected: true }, createElement(Table.DragCell, null))))));
+        stubRowRect('a');
+        const args = draggableArgsOf('a');
+        generatePreview(args);
+        startDrag(args);
+        expect(previewOverlays()[0].querySelector('.ncua-table-dnd-preview__badge')).toBeNull();
+        endDrag(args);
+    });
+    it('TB-10 drop 없이 onDragStart 가 두 번 오면 첫 오버레이가 body 에 남는다', () => {
+        // 현재 동작 고정 — 결함 후보: #588
+        // (onDragStart 가 drop 없이 다시 오면 이전 오버레이·dragover 리스너를 정리하지 않고 덮어써
+        //  첫 오버레이가 body 에 남는다. 라이브러리가 한 드래그에 onDragStart 를 두 번 부르지 않는 한 발생하지 않음)
+        render(draggableTable(vi.fn()));
+        stubRowRect('a');
+        const args = draggableArgsOf('a');
+        generatePreview(args);
+        startDrag(args);
+        startDrag(args);
+        const [stale, current] = previewOverlays();
+        endDrag(args);
+        fireDragOver(MOVE_X, MOVE_Y);
+        expect(previewOverlays()).toEqual([stale]);
+        expect(current.isConnected).toBe(false);
+        expect(stale.style.left).toBe(`${START_X - OFFSET_X}px`);
+    });
+    it.todo('TB-10 onDragStart 가 drop 없이 다시 와도 이전 오버레이·dragover 리스너를 정리한다');
+});
+describe('Table 자동 스크롤 (TB-16)', () => {
+    const MAX_HEIGHT = 300;
+    it('TB-16 draggable + fixedHeader + maxHeight 이면 scroll-container 에 autoScroll 을 등록하고 언마운트 시 해제한다', () => {
+        const view = render(customTable([{ id: 'a' }], { fixedHeader: true, maxHeight: MAX_HEIGHT }));
+        expect(autoScrollForElements).toHaveBeenCalledTimes(1);
+        expect(autoScrollForElements).toHaveBeenCalledWith({
+            element: view.querySelector('.ncua-table__scroll-container'),
+        });
+        render(createElement('div'));
+        expect(autoScrollCleanup.calls).toBe(1);
+    });
+    it.each([
+        ['fixedHeader 없음', { maxHeight: MAX_HEIGHT }],
+        ['maxHeight 없음', { fixedHeader: true }],
+        ['draggable=false', { draggable: false, fixedHeader: true, maxHeight: MAX_HEIGHT }],
+        ['type=vertical', { type: 'vertical', fixedHeader: true, maxHeight: MAX_HEIGHT }],
+    ])('TB-16 %s 이면 autoScroll 을 등록하지 않는다', (_label, props) => {
+        render(customTable([{ id: 'a' }], props));
+        expect(autoScrollForElements).not.toHaveBeenCalled();
+    });
+});
+describe('Table.DragCell 행 밖 핸들 (TB-26)', () => {
+    it('TB-26 핸들이 tr 밖에 있으면 프리뷰를 건너뛰고 onDragStart 는 is-dragging 만 붙인다', () => {
+        render(draggableTable(vi.fn()));
+        const args = draggableArgsOf('a');
+        const handle = args.element;
+        const homeRow = rowOf('a');
+        document.body.appendChild(handle);
+        try {
+            generatePreview(args);
+            startDrag(args);
+            expect(disableNativeDragPreview).not.toHaveBeenCalled();
+            expect(previewOverlays()).toHaveLength(0);
+            expect(homeRow.classList.contains('is-dragging')).toBe(true);
+            endDrag(args);
+        }
+        finally {
+            handle.remove();
+        }
+    });
+    it('TB-26 언마운트 뒤 늦게 온 onGenerateDragPreview 는 핸들 ref 가 비어 아무것도 하지 않는다', () => {
+        render(draggableTable(vi.fn()));
+        const args = draggableArgsOf('a');
+        render(createElement('div'));
+        generatePreview(args);
+        expect(disableNativeDragPreview).not.toHaveBeenCalled();
+    });
+});

package/dist/temp/src/components/data-display/table/__tests__/Table.dnd.test.d.ts

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