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

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

@@ -0,0 +1,212 @@
+"use strict";
+
+var _react = require("react");
+var _client = require("react-dom/client");
+var _testUtils = require("react-dom/test-utils");
+var _vitest = require("vitest");
+var _dndMove = require("../dnd-move");
+function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); } // @vitest-environment jsdom
+/**
+ * 묶음은 스타일 레이어이므로 드래그앤드롭 동작이 묶음 유무와 무관해야 한다.
+ * 드롭 자체는 실제 포인터 이벤트가 필요해 jsdom 으로 재현할 수 없어, 감시 등록 횟수와 콜백 전달만 고정한다.
+ */
+const monitorCalls = [];
+_vitest.vi.mock('@atlaskit/pragmatic-drag-and-drop/element/adapter', () => ({
+  dropTargetForElements: () => () => undefined,
+  draggable: () => () => undefined,
+  monitorForElements: args => {
+    monitorCalls.push(args);
+    return () => undefined;
+  }
+}));
+_vitest.vi.mock('@atlaskit/pragmatic-drag-and-drop/element/disable-native-drag-preview', () => ({
+  disableNativeDragPreview: () => undefined
+}));
+_vitest.vi.mock('@atlaskit/pragmatic-drag-and-drop-auto-scroll/element', () => ({
+  autoScrollForElements: () => () => undefined
+}));
+_vitest.vi.mock('@atlaskit/pragmatic-drag-and-drop-hitbox/closest-edge', () => ({
+  attachClosestEdge: data => data,
+  extractClosestEdge: () => 'bottom'
+}));
+const {
+  Table
+} = await Promise.resolve().then(() => _interopRequireWildcard(require('../Table')));
+let container;
+let root;
+(0, _vitest.beforeEach)(() => {
+  monitorCalls.length = 0;
+  container = document.createElement('div');
+  document.body.appendChild(container);
+  (0, _testUtils.act)(() => {
+    root = (0, _client.createRoot)(container);
+  });
+});
+(0, _vitest.afterEach)(() => {
+  (0, _testUtils.act)(() => {
+    root.unmount();
+  });
+  container.remove();
+});
+const rowProps = id => ({
+  key: id,
+  dragId: id,
+  children: /*#__PURE__*/(0, _react.createElement)(Table.Cell, null, id)
+});
+const row = id => /*#__PURE__*/(0, _react.createElement)(Table.Row, rowProps(id));
+const groupProps = (key, onRowDrop, ids) => ({
+  key,
+  onRowDrop,
+  children: ids.map(row)
+});
+const group = (key, onRowDrop, ids) => /*#__PURE__*/(0, _react.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 => {
+  (0, _testUtils.act)(() => {
+    root.render(/*#__PURE__*/(0, _react.createElement)(Table, tableProps(children)));
+  });
+};
+(0, _vitest.describe)('Table.RowGroup — 드래그앤드롭', () => {
+  (0, _vitest.it)('묶음이 여러 개여도 드롭 감시는 한 번만 등록된다', () => {
+    const onRowDrop = _vitest.vi.fn();
+    renderTable([group('g1', onRowDrop, ['a', 'b']), group('g2', onRowDrop, ['c', 'd']), group('g3', onRowDrop, ['e'])]);
+    (0, _vitest.expect)(monitorCalls).toHaveLength(1);
+  });
+  (0, _vitest.it)('묶음에 넘긴 onRowDrop 이 드롭 1회에 1번만 호출된다', () => {
+    const onRowDrop = _vitest.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'
+              }
+            }]
+          }
+        }
+      });
+    }
+    (0, _vitest.expect)(onRowDrop).toHaveBeenCalledTimes(1);
+    (0, _vitest.expect)(onRowDrop).toHaveBeenCalledWith('a', 'c', 'bottom', ['a']);
+  });
+  (0, _vitest.it)('다중 선택 드래그는 고른 행과 그 병합 블록을 모두 넘긴다', () => {
+    const onRowDrop = _vitest.vi.fn();
+    renderTable(/*#__PURE__*/(0, _react.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: (0, _dndMove.planMoveIds)(rows[0])
+        }
+      },
+      location: {
+        current: {
+          dropTargets: [{
+            data: {
+              id: 'd'
+            }
+          }]
+        }
+      }
+    });
+    (0, _vitest.expect)(onRowDrop).toHaveBeenCalledWith('a', 'd', 'bottom', ['a', 'b', 'c']);
+  });
+  (0, _vitest.it)('고르지 않은 행을 잡으면 그 행의 블록만 넘긴다', () => {
+    const onRowDrop = _vitest.vi.fn();
+    renderTable(/*#__PURE__*/(0, _react.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: (0, _dndMove.planMoveIds)(rows[0])
+        }
+      },
+      location: {
+        current: {
+          dropTargets: [{
+            data: {
+              id: 'd'
+            }
+          }]
+        }
+      }
+    });
+    (0, _vitest.expect)(onRowDrop).toHaveBeenCalledWith('a', 'd', 'bottom', ['a', 'b']);
+  });
+  (0, _vitest.it)('onRowDrop 을 거두면 드롭이 더 이상 호출되지 않는다', () => {
+    const onRowDrop = _vitest.vi.fn();
+    const drop = () => monitorCalls[0].onDrop({
+      source: {
+        data: {
+          id: 'a'
+        }
+      },
+      location: {
+        current: {
+          dropTargets: [{
+            data: {
+              id: 'b'
+            }
+          }]
+        }
+      }
+    });
+    renderTable(/*#__PURE__*/(0, _react.createElement)(Table.Body, bodyProps(onRowDrop, ['a', 'b'])));
+    drop();
+    (0, _vitest.expect)(onRowDrop).toHaveBeenCalledTimes(1);
+    (0, _testUtils.act)(() => {
+      root.render(/*#__PURE__*/(0, _react.createElement)(Table, tableProps(/*#__PURE__*/(0, _react.createElement)(Table.Body, plainBodyProps(['a', 'b'])))));
+    });
+    drop();
+    (0, _vitest.expect)(onRowDrop).toHaveBeenCalledTimes(1);
+  });
+  (0, _vitest.it)('Table.Body 의 onRowDrop 동작은 묶음 도입 전과 같다', () => {
+    const onRowDrop = _vitest.vi.fn();
+    renderTable(/*#__PURE__*/(0, _react.createElement)(Table.Body, bodyProps(onRowDrop, ['a', 'b'])));
+    (0, _vitest.expect)(monitorCalls).toHaveLength(1);
+    monitorCalls[0].onDrop({
+      source: {
+        data: {
+          id: 'a'
+        }
+      },
+      location: {
+        current: {
+          dropTargets: [{
+            data: {
+              id: 'b'
+            }
+          }]
+        }
+      }
+    });
+    (0, _vitest.expect)(onRowDrop).toHaveBeenCalledTimes(1);
+    (0, _vitest.expect)(onRowDrop).toHaveBeenCalledWith('a', 'b', 'bottom', ['a']);
+  });
+});

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

@@ -49,13 +49,16 @@ const readDefaults = () => {
     });
     (0, _vitest.expect)(() => row?.setIsDragging(true)).not.toThrow();
   });
-  (0, _vitest.it)('RSD-05 TableDndContext 기본값은 드래그 비활성 · 빈 tableId 다', () => {
+  (0, _vitest.it)('RSD-05 TableDndContext 기본값은 드래그 비활성 · 빈 tableId · 비어 있는 드롭 핸들러 자리다', () => {
     const {
       table
     } = readDefaults();
     (0, _vitest.expect)(table).toEqual({
       isDraggable: false,
-      tableId: ''
+      tableId: '',
+      onRowDropRef: {
+        current: undefined
+      }
     });
   });
 });

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

@@ -0,0 +1,75 @@
+"use strict";
+
+var _nodePath = _interopRequireDefault(require("node:path"));
+var _sass = require("sass");
+var _vitest = require("vitest");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+// box-shadow 는 jsdom 에서 계산되지 않으므로, 컴파일된 CSS 에서 규칙을 검사한다.
+// (page-title/__tests__/pageTitleStyle.test.ts 와 같은 방식)
+const TABLE_SCSS_PATH = _nodePath.default.resolve(__dirname, '../../../../../assets/styles/components/table/_index.scss');
+const compiledTableCss = (0, _sass.compile)(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';
+(0, _vitest.describe)('Table selectable — 좌측 border 보상선', () => {
+  (0, _vitest.it)('행(tr)이 보상선을 갖는다 — 병합 셀이 덮은 행의 첫 셀은 표 왼쪽 끝이 아니다', () => {
+    // Given: 컴파일된 Table CSS 에서
+    // When: selectable 의 보상 규칙을 찾으면
+    const declarations = declarationsOf(`${SELECTABLE} ${UNSELECTED_ROW}`);
+    // Then: 셀이 아니라 행 전체에 보상선을 둔다
+    (0, _vitest.expect)(declarations).toContain(COMPENSATION_LINE);
+  });
+  (0, _vitest.it)('헤더 첫 칸도 보상선을 갖는다', () => {
+    // Given/When: 헤더 첫 칸 규칙을 찾으면
+    // Then: 기존 보상선이 그대로다
+    (0, _vitest.expect)(declarationsOf(`${SELECTABLE} ${HEADER_FIRST_CELL}`)).toContain(COMPENSATION_LINE);
+  });
+});
+(0, _vitest.describe)('Table selectable — DataGrid 안에서는 보상선을 거둔다', () => {
+  (0, _vitest.it)('행(tr)의 보상선이 제거된다 — DataGrid wrapper 가 외곽 border 를 담당한다', () => {
+    // Given: 컴파일된 Table CSS 에서
+    // When: in-data-grid 조합의 행 규칙을 찾으면
+    const declarations = declarationsOf(`${IN_DATA_GRID} ${UNSELECTED_ROW}`);
+    // Then: 보상선을 지워 DataGrid 외곽선과 겹치지 않는다
+    (0, _vitest.expect)(declarations).toContain(NO_SHADOW);
+  });
+  (0, _vitest.it)('헤더 첫 칸의 보상선이 제거된다', () => {
+    // Given/When: in-data-grid 조합의 헤더 첫 칸 규칙을 찾으면
+    // Then: 보상선을 지운다
+    (0, _vitest.expect)(declarationsOf(`${IN_DATA_GRID} ${HEADER_FIRST_CELL}`)).toContain(NO_SHADOW);
+  });
+  (0, _vitest.it)('보상선을 받는 모든 자리에 제거 규칙이 대응한다 — 한쪽만 넓어지면 선이 남는다', () => {
+    // Given: 보상선을 받는 selectable 선택자를 모두 모으고
+    const compensated = [...rules].filter(_ref => {
+      let [selector, declarations] = _ref;
+      return selector.startsWith(SELECTABLE) && declarations.includes(COMPENSATION_LINE);
+    }).map(_ref2 => {
+      let [selector] = _ref2;
+      return 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: 대응 없이 남는 자리가 없다
+    (0, _vitest.expect)(compensated.length).toBeGreaterThan(0);
+    (0, _vitest.expect)(uncovered).toEqual([]);
+  });
+});

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

@@ -7,7 +7,10 @@ exports.TableDndContext = exports.RowDndContext = void 0;
 var _react = require("react");
 const TableDndContext = exports.TableDndContext = /*#__PURE__*/(0, _react.createContext)({
   isDraggable: false,
-  tableId: ''
+  tableId: '',
+  onRowDropRef: {
+    current: undefined
+  }
 });
 const RowDndContext = exports.RowDndContext = /*#__PURE__*/(0, _react.createContext)({
   dragId: undefined,

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

@@ -0,0 +1,46 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.planMoveIds = exports.locateRow = exports.findRowSpanBlock = exports.DRAG_ID_ATTRIBUTE = void 0;
+var _rowSpanBlock = require("../../../../assets/scripts/table/rowSpanBlock");
+const DRAG_ID_ATTRIBUTE = exports.DRAG_ID_ATTRIBUTE = 'data-draggable-id';
+const toDragIds = rows => rows.map(row => row.getAttribute(DRAG_ID_ATTRIBUTE)).filter(id => id !== null);
+/** 행 위치는 `tbody` 기준이라 묶음이 여러 개면 서로 겹친다 — 어느 `tbody` 인지 함께 본다 */
+const locateRow = rowEl => {
+  const located = (0, _rowSpanBlock.locateRow)(rowEl);
+  const table = located?.body.closest('table');
+  if (!located || !table) return null;
+  return {
+    ...located,
+    bodyIndex: Array.from(table.tBodies).indexOf(located.body)
+  };
+};
+/** 병합이 덮는 행은 따로 옮길 수 없다. 드래그 단위를 그 행이 속한 병합 블록으로 넓힌다. */
+exports.locateRow = locateRow;
+const findRowSpanBlock = rowEl => {
+  const located = locateRow(rowEl);
+  if (!located) return null;
+  const {
+    body,
+    bodyIndex,
+    index
+  } = located;
+  const block = (0, _rowSpanBlock.computeRowSpanBlock)((0, _rowSpanBlock.readRowSpans)(body), index);
+  return {
+    ...block,
+    bodyIndex,
+    rows: Array.from(body.rows).slice(block.start, block.end + 1)
+  };
+};
+/** 이번 드래그로 옮겨야 하는 행 전부. 고른 행이 여럿이면 각자의 병합 블록까지 끌고 온다. */
+exports.findRowSpanBlock = findRowSpanBlock;
+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 ? (0, _rowSpanBlock.expandRowsToBlocks)(selectedRows) : findRowSpanBlock(rowEl)?.rows ?? [rowEl];
+  return toDragIds(rows);
+};
+exports.planMoveIds = planMoveIds;

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

@@ -93,11 +93,16 @@ const buildRowCard = _ref => {
   wrapper.appendChild(table);
   return wrapper;
 };
-const buildDragPreview = (rows, rowRect) => {
+/**
+ * @param rows 미리보기에 그릴 행. 병합 묶음은 한 건이라도 행이 여러 개다
+ * @param itemCount 옮기는 건수. 병합 묶음은 행 수와 다르므로, 생략하면 행 수를 건수로 본다
+ */
+const buildDragPreview = function (rows, rowRect) {
+  let itemCount = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : 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);
@@ -107,7 +112,7 @@ const buildDragPreview = (rows, rowRect) => {
     width: `${PREVIEW_BADGE_HALF + rowWidth}px`,
     height: `${PREVIEW_BADGE_HALF + rowHeight + PREVIEW_STACK_OFFSET * (totalCards - 1)}px`
   });
-  if (isMulti) container.appendChild(buildCountBadge(rows.length));
+  if (isMulti) container.appendChild(buildCountBadge(itemCount));
   if (hasSummary) container.appendChild(buildSummaryCard(rowRect));
   // 뒤쪽 행 카드부터 렌더해서 앞쪽이 위로 올라오게
   for (let i = visibleCount - 1; i >= 0; i--) {

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

@@ -21,6 +21,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 를 갖는다. */
@@ -49,6 +51,8 @@ const resultKey = _ref => {
   } = _ref;
   return `${zipCode}|${roadAddress}|${jibunAddress}`;
 };
+/** 앞뒤 공백만 자르고 센다. 가운데 공백은 글자 수에 포함한다. */
+const isSearchQueryTooShort = query => query.trim().length < MIN_SEARCH_QUERY_LENGTH;
 /** SSR(도큐사우루스 등)에서는 초기값을 false(=PC)로 두고 mount 이후 갱신한다. */
 const useIsMobileViewport = () => {
   const [isMobile, setIsMobile] = (0, _react.useState)(false);
@@ -116,6 +120,10 @@ const PostcodeSearchModal = _ref2 => {
   // 검색이 실행된 검색어. 입력 중에는 갱신되지 않는다.
   // 초기값은 마운트 시점의 searchQuery — 사용처가 검색어를 채운 채로 열면 그 검색은 이미 실행된 것으로 본다.
   const [searchedQuery, setSearchedQuery] = (0, _react.useState)(searchQuery);
+  // 검색어 길이 검사에 걸렸을 때의 오류코드. 사용처 errorCode 보다 앞선다.
+  // 사용처가 결과를 지우지 않아도 이 값이 있는 동안 목록을 숨긴다(늦게 온 응답 포함).
+  const [validationErrorCode, setValidationErrorCode] = (0, _react.useState)();
+  const activeErrorCode = validationErrorCode ?? errorCode;
   // Modal 은 닫혀도 이 컴포넌트를 언마운트하지 않아 내부 상태가 다음 열기까지 남는다.
   // 열리는 순간 이전 세션의 선택·검색 상태를 지운다.
   // biome-ignore lint/correctness/useExhaustiveDependencies: searchQuery 를 deps 에 넣으면 입력할 때마다 초기화된다
@@ -123,8 +131,9 @@ const PostcodeSearchModal = _ref2 => {
     if (!open) 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;
@@ -137,6 +146,11 @@ const PostcodeSearchModal = _ref2 => {
     onSearchQueryChange(event.target.value);
   };
   const handleSearch = () => {
+    if (isSearchQueryTooShort(searchQuery)) {
+      setValidationErrorCode('E0008');
+      return;
+    }
+    setValidationErrorCode(undefined);
     setSearchedQuery(searchQuery);
     onSearch();
   };
@@ -177,7 +191,7 @@ const PostcodeSearchModal = _ref2 => {
               onKeyDown: handleSearchKeyDown,
               placeholder: SEARCH_PLACEHOLDER,
               destructive: hasError,
-              hintText: errorCode ? ERROR_HINT[errorCode] ?? DEFAULT_ERROR_HINT : undefined
+              hintText: activeErrorCode ? ERROR_HINT[activeErrorCode] ?? DEFAULT_ERROR_HINT : undefined
             }), (0, _jsxRuntime.jsx)(_button.Button, {
               className: "ncua-postcode-search-modal__search-button",
               label: SEARCH_BUTTON_LABEL,

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

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