@ncds/ui-admin 1.8.28-alpha.3 → 1.8.28-alpha.5

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

@@ -0,0 +1,137 @@
+// @vitest-environment jsdom
+/**
+ * 묶음은 스타일 레이어이므로 드래그앤드롭 동작이 묶음 유무와 무관해야 한다.
+ * 드롭 자체는 실제 포인터 이벤트가 필요해 jsdom 으로 재현할 수 없어, 감시 등록 횟수와 콜백 전달만 고정한다.
+ */
+import { createElement } from 'react';
+import { createRoot } from 'react-dom/client';
+import { act } from 'react-dom/test-utils';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+const monitorCalls = [];
+vi.mock('@atlaskit/pragmatic-drag-and-drop/element/adapter', () => ({
+    dropTargetForElements: () => () => undefined,
+    draggable: () => () => undefined,
+    monitorForElements: (args) => {
+        monitorCalls.push(args);
+        return () => undefined;
+    },
+}));
+vi.mock('@atlaskit/pragmatic-drag-and-drop/element/disable-native-drag-preview', () => ({
+    disableNativeDragPreview: () => undefined,
+}));
+vi.mock('@atlaskit/pragmatic-drag-and-drop-auto-scroll/element', () => ({
+    autoScrollForElements: () => () => undefined,
+}));
+vi.mock('@atlaskit/pragmatic-drag-and-drop-hitbox/closest-edge', () => ({
+    attachClosestEdge: (data) => data,
+    extractClosestEdge: () => 'bottom',
+}));
+import { planMoveIds } from '../dnd-move';
+const { Table } = await import('../Table');
+let container;
+let root;
+beforeEach(() => {
+    monitorCalls.length = 0;
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    act(() => {
+        root = createRoot(container);
+    });
+});
+afterEach(() => {
+    act(() => {
+        root.unmount();
+    });
+    container.remove();
+});
+const rowProps = (id) => ({ key: id, dragId: id, children: createElement(Table.Cell, null, id) });
+const row = (id) => createElement(Table.Row, rowProps(id));
+const groupProps = (key, onRowDrop, ids) => ({
+    key,
+    onRowDrop,
+    children: ids.map(row),
+});
+const group = (key, onRowDrop, ids) => createElement(Table.RowGroup, groupProps(key, onRowDrop, ids));
+const bodyProps = (onRowDrop, ids) => ({ onRowDrop, children: ids.map(row) });
+const plainBodyProps = (ids) => ({ children: ids.map(row) });
+const tableProps = (children) => ({ type: 'horizontal', draggable: true, children });
+const renderTable = (children) => {
+    act(() => {
+        root.render(createElement(Table, tableProps(children)));
+    });
+};
+describe('Table.RowGroup — 드래그앤드롭', () => {
+    it('묶음이 여러 개여도 드롭 감시는 한 번만 등록된다', () => {
+        const onRowDrop = vi.fn();
+        renderTable([
+            group('g1', onRowDrop, ['a', 'b']),
+            group('g2', onRowDrop, ['c', 'd']),
+            group('g3', onRowDrop, ['e']),
+        ]);
+        expect(monitorCalls).toHaveLength(1);
+    });
+    it('묶음에 넘긴 onRowDrop 이 드롭 1회에 1번만 호출된다', () => {
+        const onRowDrop = vi.fn();
+        renderTable([group('g1', onRowDrop, ['a', 'b']), group('g2', onRowDrop, ['c', 'd'])]);
+        for (const call of monitorCalls) {
+            call.onDrop({
+                source: { data: { id: 'a' } },
+                location: { current: { dropTargets: [{ data: { id: 'c' } }] } },
+            });
+        }
+        expect(onRowDrop).toHaveBeenCalledTimes(1);
+        expect(onRowDrop).toHaveBeenCalledWith('a', 'c', 'bottom', ['a']);
+    });
+    it('다중 선택 드래그는 고른 행과 그 병합 블록을 모두 넘긴다', () => {
+        const onRowDrop = vi.fn();
+        renderTable(createElement(Table.Body, bodyProps(onRowDrop, ['a', 'b', 'c', 'd'])));
+        const rows = Array.from(container.querySelectorAll('tbody tr'));
+        // a 가 b 를 덮고, c 는 혼자다 — a·c 를 고르면 b 도 따라와야 한다
+        rows[0].cells[0].rowSpan = 2;
+        rows[0].classList.add('ncua-table__row--selected');
+        rows[2].classList.add('ncua-table__row--selected');
+        monitorCalls[0].onDrop({
+            source: { data: { id: 'a', moveIds: planMoveIds(rows[0]) } },
+            location: { current: { dropTargets: [{ data: { id: 'd' } }] } },
+        });
+        expect(onRowDrop).toHaveBeenCalledWith('a', 'd', 'bottom', ['a', 'b', 'c']);
+    });
+    it('고르지 않은 행을 잡으면 그 행의 블록만 넘긴다', () => {
+        const onRowDrop = vi.fn();
+        renderTable(createElement(Table.Body, bodyProps(onRowDrop, ['a', 'b', 'c', 'd'])));
+        const rows = Array.from(container.querySelectorAll('tbody tr'));
+        rows[0].cells[0].rowSpan = 2;
+        rows[2].classList.add('ncua-table__row--selected');
+        monitorCalls[0].onDrop({
+            source: { data: { id: 'a', moveIds: planMoveIds(rows[0]) } },
+            location: { current: { dropTargets: [{ data: { id: 'd' } }] } },
+        });
+        expect(onRowDrop).toHaveBeenCalledWith('a', 'd', 'bottom', ['a', 'b']);
+    });
+    it('onRowDrop 을 거두면 드롭이 더 이상 호출되지 않는다', () => {
+        const onRowDrop = vi.fn();
+        const drop = () => monitorCalls[0].onDrop({
+            source: { data: { id: 'a' } },
+            location: { current: { dropTargets: [{ data: { id: 'b' } }] } },
+        });
+        renderTable(createElement(Table.Body, bodyProps(onRowDrop, ['a', 'b'])));
+        drop();
+        expect(onRowDrop).toHaveBeenCalledTimes(1);
+        act(() => {
+            root.render(createElement(Table, tableProps(createElement(Table.Body, plainBodyProps(['a', 'b'])))));
+        });
+        drop();
+        expect(onRowDrop).toHaveBeenCalledTimes(1);
+    });
+    it('Table.Body 의 onRowDrop 동작은 묶음 도입 전과 같다', () => {
+        const onRowDrop = vi.fn();
+        renderTable(createElement(Table.Body, bodyProps(onRowDrop, ['a', 'b'])));
+        expect(monitorCalls).toHaveLength(1);
+        monitorCalls[0].onDrop({
+            source: { data: { id: 'a' } },
+            location: { current: { dropTargets: [{ data: { id: 'b' } }] } },
+        });
+        expect(onRowDrop).toHaveBeenCalledTimes(1);
+        expect(onRowDrop).toHaveBeenCalledWith('a', 'b', 'bottom', ['a']);
+    });
+});

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

@@ -35,8 +35,8 @@ describe('dnd-context — Provider 밖 기본값 (RSD-05)', () => {
         expect(row).toEqual({ dragId: undefined, setIsDragging: expect.any(Function) });
         expect(() => row?.setIsDragging(true)).not.toThrow();
     });
-    it('RSD-05 TableDndContext 기본값은 드래그 비활성 · 빈 tableId 다', () => {
+    it('RSD-05 TableDndContext 기본값은 드래그 비활성 · 빈 tableId · 비어 있는 드롭 핸들러 자리다', () => {
         const { table } = readDefaults();
-        expect(table).toEqual({ isDraggable: false, tableId: '' });
+        expect(table).toEqual({ isDraggable: false, tableId: '', onRowDropRef: { current: undefined } });
     });
 });

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

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

package/dist/temp/src/components/data-display/table/__tests__/tableSelectableStyle.test.js

@@ -0,0 +1,71 @@
+import path from 'node:path';
+import { compile as compileSass } from 'sass';
+import { describe, expect, it } from 'vitest';
+// box-shadow 는 jsdom 에서 계산되지 않으므로, 컴파일된 CSS 에서 규칙을 검사한다.
+// (page-title/__tests__/pageTitleStyle.test.ts 와 같은 방식)
+const TABLE_SCSS_PATH = path.resolve(__dirname, '../../../../../assets/styles/components/table/_index.scss');
+const compiledTableCss = compileSass(TABLE_SCSS_PATH).css;
+/** 선택자 → 선언 목록. 같은 선택자가 여러 규칙에 나오면 선언을 이어 붙인다. */
+const parseRules = (css) => {
+    const rules = new Map();
+    for (const [, selectorList, body] of css.matchAll(/([^{}]+)\{([^{}]*)\}/g)) {
+        const declarations = body
+            .split(';')
+            .map((declaration) => declaration.trim().replace(/\s+/g, ' '))
+            .filter(Boolean);
+        for (const selector of selectorList.split(',').map((selector) => selector.trim().replace(/\s+/g, ' '))) {
+            rules.set(selector, [...(rules.get(selector) ?? []), ...declarations]);
+        }
+    }
+    return rules;
+};
+const rules = parseRules(compiledTableCss);
+const declarationsOf = (selector) => rules.get(selector) ?? [];
+const SELECTABLE = '.ncua-table--selectable';
+const IN_DATA_GRID = '.ncua-table--in-data-grid.ncua-table--selectable';
+const UNSELECTED_ROW = '.ncua-table__body .ncua-table__row:not(.ncua-table__row--selected)';
+const HEADER_FIRST_CELL = '.ncua-table__header-cell:first-child';
+const COMPENSATION_LINE = 'box-shadow: inset 1px 0 0 0 var(--gray-100)';
+const NO_SHADOW = 'box-shadow: none';
+describe('Table selectable — 좌측 border 보상선', () => {
+    it('행(tr)이 보상선을 갖는다 — 병합 셀이 덮은 행의 첫 셀은 표 왼쪽 끝이 아니다', () => {
+        // Given: 컴파일된 Table CSS 에서
+        // When: selectable 의 보상 규칙을 찾으면
+        const declarations = declarationsOf(`${SELECTABLE} ${UNSELECTED_ROW}`);
+        // Then: 셀이 아니라 행 전체에 보상선을 둔다
+        expect(declarations).toContain(COMPENSATION_LINE);
+    });
+    it('헤더 첫 칸도 보상선을 갖는다', () => {
+        // Given/When: 헤더 첫 칸 규칙을 찾으면
+        // Then: 기존 보상선이 그대로다
+        expect(declarationsOf(`${SELECTABLE} ${HEADER_FIRST_CELL}`)).toContain(COMPENSATION_LINE);
+    });
+});
+describe('Table selectable — DataGrid 안에서는 보상선을 거둔다', () => {
+    it('행(tr)의 보상선이 제거된다 — DataGrid wrapper 가 외곽 border 를 담당한다', () => {
+        // Given: 컴파일된 Table CSS 에서
+        // When: in-data-grid 조합의 행 규칙을 찾으면
+        const declarations = declarationsOf(`${IN_DATA_GRID} ${UNSELECTED_ROW}`);
+        // Then: 보상선을 지워 DataGrid 외곽선과 겹치지 않는다
+        expect(declarations).toContain(NO_SHADOW);
+    });
+    it('헤더 첫 칸의 보상선이 제거된다', () => {
+        // Given/When: in-data-grid 조합의 헤더 첫 칸 규칙을 찾으면
+        // Then: 보상선을 지운다
+        expect(declarationsOf(`${IN_DATA_GRID} ${HEADER_FIRST_CELL}`)).toContain(NO_SHADOW);
+    });
+    it('보상선을 받는 모든 자리에 제거 규칙이 대응한다 — 한쪽만 넓어지면 선이 남는다', () => {
+        // Given: 보상선을 받는 selectable 선택자를 모두 모으고
+        const compensated = [...rules]
+            .filter(([selector, declarations]) => selector.startsWith(SELECTABLE) && declarations.includes(COMPENSATION_LINE))
+            .map(([selector]) => selector);
+        // When: 각 선택자의 in-data-grid 대응 규칙을 찾으면
+        const uncovered = compensated.filter((selector) => {
+            const counterpart = selector.replace(SELECTABLE, IN_DATA_GRID);
+            return !declarationsOf(counterpart).includes(NO_SHADOW);
+        });
+        // Then: 대응 없이 남는 자리가 없다
+        expect(compensated.length).toBeGreaterThan(0);
+        expect(uncovered).toEqual([]);
+    });
+});

package/dist/temp/src/components/data-display/table/dnd-context.d.ts

@@ -1,6 +1,9 @@
+import { type MutableRefObject } from 'react';
+import type { TableRowDropHandler } from './types';
 type TableDndContextValue = {
     isDraggable: boolean;
     tableId: string;
+    onRowDropRef: MutableRefObject<TableRowDropHandler | undefined>;
 };
 declare const TableDndContext: import("react").Context<TableDndContextValue>;
 type RowDndContextValue = {

package/dist/temp/src/components/data-display/table/dnd-context.js

@@ -2,6 +2,7 @@ import { createContext } from 'react';
 const TableDndContext = createContext({
     isDraggable: false,
     tableId: '',
+    onRowDropRef: { current: undefined },
 });
 const RowDndContext = createContext({
     dragId: undefined,

package/dist/temp/src/components/data-display/table/dnd-move.d.ts

@@ -0,0 +1,17 @@
+declare const DRAG_ID_ATTRIBUTE = "data-draggable-id";
+/** 행 위치는 `tbody` 기준이라 묶음이 여러 개면 서로 겹친다 — 어느 `tbody` 인지 함께 본다 */
+export declare const locateRow: (rowEl: HTMLTableRowElement) => {
+    bodyIndex: number;
+    body: HTMLTableSectionElement;
+    index: number;
+} | null;
+/** 병합이 덮는 행은 따로 옮길 수 없다. 드래그 단위를 그 행이 속한 병합 블록으로 넓힌다. */
+export declare const findRowSpanBlock: (rowEl: HTMLTableRowElement) => {
+    bodyIndex: number;
+    rows: HTMLTableRowElement[];
+    start: number;
+    end: number;
+} | null;
+/** 이번 드래그로 옮겨야 하는 행 전부. 고른 행이 여럿이면 각자의 병합 블록까지 끌고 온다. */
+export declare const planMoveIds: (rowEl: HTMLTableRowElement) => string[];
+export { DRAG_ID_ATTRIBUTE };

package/dist/temp/src/components/data-display/table/dnd-move.js

@@ -0,0 +1,31 @@
+import { computeRowSpanBlock, expandRowsToBlocks, locateRow as locateInBody, readRowSpans, } from '../../../../assets/scripts/table/rowSpanBlock';
+const DRAG_ID_ATTRIBUTE = 'data-draggable-id';
+const toDragIds = (rows) => rows.map((row) => row.getAttribute(DRAG_ID_ATTRIBUTE)).filter((id) => id !== null);
+/** 행 위치는 `tbody` 기준이라 묶음이 여러 개면 서로 겹친다 — 어느 `tbody` 인지 함께 본다 */
+export const locateRow = (rowEl) => {
+    const located = locateInBody(rowEl);
+    const table = located?.body.closest('table');
+    if (!located || !table)
+        return null;
+    return { ...located, bodyIndex: Array.from(table.tBodies).indexOf(located.body) };
+};
+/** 병합이 덮는 행은 따로 옮길 수 없다. 드래그 단위를 그 행이 속한 병합 블록으로 넓힌다. */
+export const findRowSpanBlock = (rowEl) => {
+    const located = locateRow(rowEl);
+    if (!located)
+        return null;
+    const { body, bodyIndex, index } = located;
+    const block = computeRowSpanBlock(readRowSpans(body), index);
+    return { ...block, bodyIndex, rows: Array.from(body.rows).slice(block.start, block.end + 1) };
+};
+/** 이번 드래그로 옮겨야 하는 행 전부. 고른 행이 여럿이면 각자의 병합 블록까지 끌고 온다. */
+export const planMoveIds = (rowEl) => {
+    const tableEl = rowEl.closest('table');
+    const selectedRows = tableEl
+        ? Array.from(tableEl.querySelectorAll('tbody > .ncua-table__row--selected'))
+        : [];
+    const isMultiSelect = selectedRows.length > 1 && selectedRows.includes(rowEl);
+    const rows = isMultiSelect ? expandRowsToBlocks(selectedRows) : (findRowSpanBlock(rowEl)?.rows ?? [rowEl]);
+    return toDragIds(rows);
+};
+export { DRAG_ID_ATTRIBUTE };

package/dist/temp/src/components/data-display/table/dnd-preview.d.ts

@@ -2,5 +2,9 @@ declare const TABLE_DND_ID_RADIX = 36;
 declare const TABLE_DND_ID_SLICE_START = 2;
 declare const TABLE_DND_ID_SLICE_END = 9;
 declare const PREVIEW_BADGE_SIZE = 24;
-declare const buildDragPreview: (rows: HTMLElement[], rowRect: DOMRect) => HTMLDivElement;
+/**
+ * @param rows 미리보기에 그릴 행. 병합 묶음은 한 건이라도 행이 여러 개다
+ * @param itemCount 옮기는 건수. 병합 묶음은 행 수와 다르므로, 생략하면 행 수를 건수로 본다
+ */
+declare const buildDragPreview: (rows: HTMLElement[], rowRect: DOMRect, itemCount?: number) => HTMLDivElement;
 export { TABLE_DND_ID_RADIX, TABLE_DND_ID_SLICE_START, TABLE_DND_ID_SLICE_END, PREVIEW_BADGE_SIZE, buildDragPreview };

package/dist/temp/src/components/data-display/table/dnd-preview.js

@@ -84,11 +84,15 @@ const buildRowCard = ({ row, cardLeft, cardTop, cardWidth, rowHeight, zIndex, pa
     wrapper.appendChild(table);
     return wrapper;
 };
-const buildDragPreview = (rows, rowRect) => {
+/**
+ * @param rows 미리보기에 그릴 행. 병합 묶음은 한 건이라도 행이 여러 개다
+ * @param itemCount 옮기는 건수. 병합 묶음은 행 수와 다르므로, 생략하면 행 수를 건수로 본다
+ */
+const buildDragPreview = (rows, rowRect, itemCount = rows.length) => {
     const visibleCount = Math.min(rows.length, PREVIEW_MAX_ROWS);
     const hasSummary = rows.length > visibleCount;
     const totalCards = visibleCount + (hasSummary ? 1 : 0);
-    const isMulti = rows.length > 1;
+    const isMulti = itemCount > 1;
     const parentTable = rows[0]?.closest('table') ?? null;
     const rowWidth = Math.round(rowRect.width);
     const rowHeight = Math.round(rowRect.height);
@@ -99,7 +103,7 @@ const buildDragPreview = (rows, rowRect) => {
         height: `${PREVIEW_BADGE_HALF + rowHeight + PREVIEW_STACK_OFFSET * (totalCards - 1)}px`,
     });
     if (isMulti)
-        container.appendChild(buildCountBadge(rows.length));
+        container.appendChild(buildCountBadge(itemCount));
     if (hasSummary)
         container.appendChild(buildSummaryCard(rowRect));
     // 뒤쪽 행 카드부터 렌더해서 앞쪽이 위로 올라오게

package/dist/temp/src/components/data-display/table/types.d.ts

@@ -30,14 +30,21 @@ export type TableHeaderProps = {
     children: ReactNode;
     className?: string;
 };
+/**
+ * draggable=true 테이블에서 행이 재정렬될 때 호출된다.
+ * fromId → toId 로 이동, edge는 toId 행의 위(top)/아래(bottom) 삽입 위치.
+ * @param moveIds 이번 드래그로 옮겨야 하는 행 전부 — 다중 선택과 각 행의 병합 블록을 모두 반영한다
+ */
+export type TableRowDropHandler = (fromId: string, toId: string, edge: 'top' | 'bottom', moveIds: string[]) => void;
 export type TableBodyProps = {
     children: ReactNode;
     className?: string;
-    /**
-     * draggable=true 테이블에서 행이 재정렬될 때 호출된다.
-     * fromId → toId 로 이동, edge는 toId 행의 위(top)/아래(bottom) 삽입 위치.
-     */
-    onRowDrop?: (fromId: string, toId: string, edge: 'top' | 'bottom') => void;
+    onRowDrop?: TableRowDropHandler;
+};
+export type TableRowGroupProps = {
+    children: ReactNode;
+    className?: string;
+    onRowDrop?: TableRowDropHandler;
 };
 export type TableRowProps = Omit<ComponentProps<'tr'>, 'ref'> & {
     selected?: boolean;
@@ -48,6 +55,8 @@ export type TableRowProps = Omit<ComponentProps<'tr'>, 'ref'> & {
 export type TableDragCellProps = {
     disabled?: boolean;
     className?: string;
+    /** 묶음에서 여러 행을 덮을 때 지정한다. 다른 칸과 달리 병합되지 않으면 묶음 첫 칸만 쪼개져 보인다. */
+    rowSpan?: number;
     /** 드래그 셀에 함께 배치할 콘텐츠 (예: CheckboxInput). 아이콘 우측 8px gap으로 배치된다. */
     children?: ReactNode;
 };

package/dist/temp/src/components/overlays/postcode-search-modal/PostcodeSearchModal.js

@@ -14,6 +14,8 @@ const PAGE_SIZE = 15;
 const PAGER_WINDOW = 10;
 /** 검색 조합 안내 문구를 띄우는 기준 — 결과가 이 수를 넘을 때만 노출한다 */
 const SEARCH_HINT_MIN_TOTAL_COUNT = 30;
+/** 기획서 케이스 2 — 이 길이 미만이면 검색하지 않는다 */
+const MIN_SEARCH_QUERY_LENGTH = 2;
 /** 반응형 전환 기준 — assets/styles/base/_variable.scss 의 $breakpoint 와 동일 */
 const MOBILE_BREAKPOINT = 768;
 /** 본문 스크롤 컨테이너. Modal.Content 가 overflow-y:auto 를 갖는다. */
@@ -35,6 +37,8 @@ const ERROR_HINT = {
 };
 /** 선택 표시를 판정하는 키. 우편번호만으로는 같은 건물의 다른 지번을 구분하지 못한다. */
 const resultKey = ({ zipCode, roadAddress, jibunAddress }) => `${zipCode}|${roadAddress}|${jibunAddress}`;
+/** 앞뒤 공백만 자르고 센다. 가운데 공백은 글자 수에 포함한다. */
+const isSearchQueryTooShort = (query) => query.trim().length < MIN_SEARCH_QUERY_LENGTH;
 /** SSR(도큐사우루스 등)에서는 초기값을 false(=PC)로 두고 mount 이후 갱신한다. */
 const useIsMobileViewport = () => {
     const [isMobile, setIsMobile] = useState(false);
@@ -85,6 +89,10 @@ const PostcodeSearchModal = ({ open, onClose, zIndex, className, searchQuery, on
     // 검색이 실행된 검색어. 입력 중에는 갱신되지 않는다.
     // 초기값은 마운트 시점의 searchQuery — 사용처가 검색어를 채운 채로 열면 그 검색은 이미 실행된 것으로 본다.
     const [searchedQuery, setSearchedQuery] = useState(searchQuery);
+    // 검색어 길이 검사에 걸렸을 때의 오류코드. 사용처 errorCode 보다 앞선다.
+    // 사용처가 결과를 지우지 않아도 이 값이 있는 동안 목록을 숨긴다(늦게 온 응답 포함).
+    const [validationErrorCode, setValidationErrorCode] = useState();
+    const activeErrorCode = validationErrorCode ?? errorCode;
     // Modal 은 닫혀도 이 컴포넌트를 언마운트하지 않아 내부 상태가 다음 열기까지 남는다.
     // 열리는 순간 이전 세션의 선택·검색 상태를 지운다.
     // biome-ignore lint/correctness/useExhaustiveDependencies: searchQuery 를 deps 에 넣으면 입력할 때마다 초기화된다
@@ -93,8 +101,9 @@ const PostcodeSearchModal = ({ open, onClose, zIndex, className, searchQuery, on
             return;
         setSelectedKey(undefined);
         setSearchedQuery(searchQuery);
+        setValidationErrorCode(undefined);
     }, [open]);
-    const hasError = Boolean(errorCode);
+    const hasError = Boolean(activeErrorCode);
     const hasResults = !hasError && results.length > 0;
     // 결과가 적으면 굳이 검색 조합을 안내하지 않는다.
     const showSearchHint = hasResults && totalCount > SEARCH_HINT_MIN_TOTAL_COUNT;
@@ -107,6 +116,11 @@ const PostcodeSearchModal = ({ open, onClose, zIndex, className, searchQuery, on
         onSearchQueryChange(event.target.value);
     };
     const handleSearch = () => {
+        if (isSearchQueryTooShort(searchQuery)) {
+            setValidationErrorCode('E0008');
+            return;
+        }
+        setValidationErrorCode(undefined);
         setSearchedQuery(searchQuery);
         onSearch();
     };
@@ -119,7 +133,7 @@ const PostcodeSearchModal = ({ open, onClose, zIndex, className, searchQuery, on
     };
     return (_jsxs(Modal, { isOpen: open, onClose: onClose, size: "md", zIndex: zIndex, className: className, children: [_jsx(Modal.Header, { title: MODAL_TITLE, onClose: onClose, showDivider: true }), _jsx(Modal.Content, { children: _jsxs("div", { className: "ncua-postcode-search-modal", ref: rootRef, children: [_jsxs("div", { className: classnames('ncua-postcode-search-modal__search-area', {
                                 'is-fixed': hasResults && isContentScrolled,
-                            }), children: [_jsxs("div", { className: "ncua-postcode-search-modal__search", children: [_jsx(InputBase, { className: "ncua-postcode-search-modal__search-input", size: "sm", fullWidth: true, value: searchQuery, clearText: !!searchQuery, onClearText: () => onSearchQueryChange(''), onChange: handleSearchQueryChange, onKeyDown: handleSearchKeyDown, placeholder: SEARCH_PLACEHOLDER, destructive: hasError, hintText: errorCode ? (ERROR_HINT[errorCode] ?? DEFAULT_ERROR_HINT) : undefined }), _jsx(Button, { className: "ncua-postcode-search-modal__search-button", label: SEARCH_BUTTON_LABEL, size: "sm", hierarchy: "secondary", onClick: handleSearch })] }), showSearchHint && (_jsxs("div", { children: [_jsx("p", { className: "ncua-postcode-search-modal__result-title", children: "\uC544\uB798 \uC870\uD569\uC73C\uB85C \uAC80\uC0C9 \uC2DC \uC8FC\uC18C\uB97C \uB354 \uC27D\uAC8C \uCC3E\uC744 \uC218 \uC788\uC5B4\uC694." }), _jsx("p", { className: "ncua-postcode-search-modal__result-desc", children: "\uB3C4\uB85C\uBA85+\uAC74\uBB3C\uBC88\uD638, \uC9C0\uC5ED\uBA85+\uC9C0\uBC88, \uC9C0\uC5ED\uBA85+\uAC74\uBB3C\uBA85(\uC544\uD30C\uD2B8\uBA85)" })] }))] }), !hasResults && _jsx(PostcodeSearchModal.Tip, {}), hasResults && (_jsxs(_Fragment, { children: [_jsxs("p", { className: "ncua-postcode-search-modal__count", children: ["\uAC80\uC0C9 ", _jsx("b", { children: totalCount }), "\uAC1C"] }), _jsx("ul", { className: "ncua-postcode-search-modal__list", children: results.map((result, index) => (_jsx("li", { className: "ncua-postcode-search-modal__item", children: _jsx(Radio, { name: RESULT_RADIO_NAME, value: result.zipCode, checked: selectedKey === resultKey(result), onChange: () => {
+                            }), children: [_jsxs("div", { className: "ncua-postcode-search-modal__search", children: [_jsx(InputBase, { className: "ncua-postcode-search-modal__search-input", size: "sm", fullWidth: true, value: searchQuery, clearText: !!searchQuery, onClearText: () => onSearchQueryChange(''), onChange: handleSearchQueryChange, onKeyDown: handleSearchKeyDown, placeholder: SEARCH_PLACEHOLDER, destructive: hasError, hintText: activeErrorCode ? (ERROR_HINT[activeErrorCode] ?? DEFAULT_ERROR_HINT) : undefined }), _jsx(Button, { className: "ncua-postcode-search-modal__search-button", label: SEARCH_BUTTON_LABEL, size: "sm", hierarchy: "secondary", onClick: handleSearch })] }), showSearchHint && (_jsxs("div", { children: [_jsx("p", { className: "ncua-postcode-search-modal__result-title", children: "\uC544\uB798 \uC870\uD569\uC73C\uB85C \uAC80\uC0C9 \uC2DC \uC8FC\uC18C\uB97C \uB354 \uC27D\uAC8C \uCC3E\uC744 \uC218 \uC788\uC5B4\uC694." }), _jsx("p", { className: "ncua-postcode-search-modal__result-desc", children: "\uB3C4\uB85C\uBA85+\uAC74\uBB3C\uBC88\uD638, \uC9C0\uC5ED\uBA85+\uC9C0\uBC88, \uC9C0\uC5ED\uBA85+\uAC74\uBB3C\uBA85(\uC544\uD30C\uD2B8\uBA85)" })] }))] }), !hasResults && _jsx(PostcodeSearchModal.Tip, {}), hasResults && (_jsxs(_Fragment, { children: [_jsxs("p", { className: "ncua-postcode-search-modal__count", children: ["\uAC80\uC0C9 ", _jsx("b", { children: totalCount }), "\uAC1C"] }), _jsx("ul", { className: "ncua-postcode-search-modal__list", children: results.map((result, index) => (_jsx("li", { className: "ncua-postcode-search-modal__item", children: _jsx(Radio, { name: RESULT_RADIO_NAME, value: result.zipCode, checked: selectedKey === resultKey(result), onChange: () => {
                                                 setSelectedKey(resultKey(result));
                                                 onSelect(result);
                                             }, text: _jsxs(_Fragment, { children: [_jsxs("span", { className: "ncua-postcode-search-modal__addr-line", children: [_jsx("span", { className: "ncua-postcode-search-modal__badge", children: ROAD_BADGE_LABEL }), _jsx("span", { className: "ncua-postcode-search-modal__item-road", children: result.roadAddress }), _jsx("span", { className: "ncua-postcode-search-modal__item-zip", children: result.zipCode })] }), _jsxs("span", { className: "ncua-postcode-search-modal__addr-line", children: [_jsx("span", { className: "ncua-postcode-search-modal__badge", children: JIBUN_BADGE_LABEL }), _jsx("span", { className: "ncua-postcode-search-modal__item-jibun", children: result.jibunAddress })] })] }) }) }, `${result.zipCode}-${index}`))) }), _jsx("div", { className: "ncua-postcode-search-modal__pagination", children: _jsx(Pagination, { totalCount: totalCount, itemCountPerPage: pageSize, pageCount: PAGER_WINDOW, currentPage: currentPage, breakPoint: isMobile ? 'mo' : 'pc', onPageChange: onPageChange }) })] })), showEmptyState && (_jsx("div", { className: "ncua-postcode-search-modal__empty", children: _jsx(EmptyState, { title: EMPTY_TITLE, description: EMPTY_DESCRIPTION }) }))] }) })] }));

package/dist/temp/src/components/overlays/postcode-search-modal/__tests__/PostcodeSearchModal.test.js

@@ -501,3 +501,95 @@ describe('PostcodeSearchModal — 검색 영역 고정 표시', () => {
         expect(isFixedSearchArea(el)).toBe(false);
     });
 });
+describe('PostcodeSearchModal — 검색어 2글자 미만 검사 (#678)', () => {
+    const SHORT_QUERY_HINT = '검색어를 두 글자 이상 입력해주세요.';
+    const searchButtonOf = (el) => el.querySelector('.ncua-postcode-search-modal__search-button');
+    const clickSearch = (el) => {
+        act(() => {
+            searchButtonOf(el)?.click();
+        });
+    };
+    it.each(['', '   ', '가', ' 가 '])('trim 후 2글자 미만("%s")이면 onSearch 를 부르지 않고 오류 문구를 보인다', (searchQuery) => {
+        // Given: 검색어가 trim 후 2글자 미만인 상태에서
+        const onSearch = vi.fn();
+        const el = render(baseProps({ searchQuery, onSearch }));
+        // When: 검색 버튼을 누르면
+        clickSearch(el);
+        // Then: 검색은 실행되지 않고 입력칸이 오류 상태가 된다
+        expect(onSearch).not.toHaveBeenCalled();
+        expect(hintOf(el)?.textContent).toBe(SHORT_QUERY_HINT);
+        expect(inputRootOf(el)?.classList.contains('destructive')).toBe(true);
+    });
+    it.each(['가나', ' 가나 '])('trim 후 2글자 이상("%s")이면 onSearch 를 부르고 오류가 없다', (searchQuery) => {
+        // Given: 검색어가 trim 후 2글자 이상인 상태에서
+        const onSearch = vi.fn();
+        const el = render(baseProps({ searchQuery, onSearch }));
+        // When: 검색 버튼을 누르면
+        clickSearch(el);
+        // Then: 검색이 실행되고 입력칸은 오류 상태가 아니다
+        expect(onSearch).toHaveBeenCalledTimes(1);
+        expect(hintOf(el)).toBeNull();
+        expect(inputRootOf(el)?.classList.contains('destructive')).toBe(false);
+    });
+    it('결과를 보여 주는 중에 1글자로 검색하면 목록·페이지네이션을 숨기고 Tip 을 보인다', () => {
+        // Given: 결과가 보이는 상태에서 검색어를 1글자로 바꾸고
+        const results = makeResults(SMALL_RESULT_COUNT);
+        render(baseProps({ searchQuery: '판교로', results, totalCount: SMALL_RESULT_COUNT }));
+        const el = render(baseProps({ searchQuery: '가', results, totalCount: SMALL_RESULT_COUNT }));
+        expect(itemsOf(el)).toHaveLength(SMALL_RESULT_COUNT);
+        // When: 검색 버튼을 누르면
+        clickSearch(el);
+        // Then: 사용처가 결과를 지우지 않아도 지난 목록은 보이지 않는다
+        expect(el.querySelector('.ncua-postcode-search-modal__list')).toBeNull();
+        expect(paginationOf(el)).toBeNull();
+        expect(tipOf(el)).not.toBeNull();
+    });
+    it('검사에 걸린 뒤 2글자 이상으로 다시 검색하면 오류가 풀리고 onSearch 를 부른다', () => {
+        // Given: 1글자로 검색해 검사에 걸린 상태에서
+        const onSearch = vi.fn();
+        const el = render(baseProps({ searchQuery: '가', onSearch }));
+        clickSearch(el);
+        // When: 2글자로 고쳐 다시 검색하면
+        render(baseProps({ searchQuery: '가나', onSearch }));
+        clickSearch(el);
+        // Then: 오류가 풀리고 검색이 실행된다
+        expect(onSearch).toHaveBeenCalledTimes(1);
+        expect(hintOf(el)).toBeNull();
+        expect(inputRootOf(el)?.classList.contains('destructive')).toBe(false);
+    });
+    it('검사에 걸린 뒤 모달을 닫았다 다시 열면 오류가 없다', () => {
+        // Given: 1글자로 검색해 검사에 걸린 상태에서
+        const el = render(baseProps({ searchQuery: '가' }));
+        clickSearch(el);
+        // When: 모달을 닫았다가 다시 열면
+        render(baseProps({ open: false, searchQuery: '가' }));
+        const reopened = render(baseProps({ searchQuery: '가' }));
+        // Then: 지난 검사 오류는 남지 않는다
+        expect(hintOf(reopened)).toBeNull();
+        expect(inputRootOf(reopened)?.classList.contains('destructive')).toBe(false);
+    });
+    it('앱 errorCode(E0006) 가 있어도 1글자로 검색하면 검사 오류 문구(E0008)를 보인다', () => {
+        // Given: 사용처가 E0006 을 넘긴 상태에서 검색어를 1글자로 바꾸고
+        const el = render(baseProps({ searchQuery: '가', errorCode: 'E0006' }));
+        // When: 검색 버튼을 누르면
+        clickSearch(el);
+        // Then: 컴포넌트 검사 오류가 앞선다
+        expect(hintOf(el)?.textContent).toBe(SHORT_QUERY_HINT);
+    });
+    it('Enter 로 1글자 검색해도 버튼과 같이 onSearch 를 부르지 않고 오류 문구를 보인다', () => {
+        // Given: 검색어가 1글자인 상태에서
+        const onSearch = vi.fn();
+        const el = render(baseProps({ searchQuery: '가', onSearch }));
+        const input = el.querySelector('.ncua-input input');
+        if (!input)
+            throw new Error('검색 인풋이 렌더되지 않았습니다');
+        // When: Enter 를 누르면
+        act(() => {
+            input.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }));
+        });
+        // Then: 버튼을 누른 것과 결과가 같다
+        expect(onSearch).not.toHaveBeenCalled();
+        expect(hintOf(el)?.textContent).toBe(SHORT_QUERY_HINT);
+        expect(inputRootOf(el)?.classList.contains('destructive')).toBe(true);
+    });
+});