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

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);
+  });
 });

package/dist/esm/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 를 갖는다. */
@@ -42,6 +44,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] = useState(false);
@@ -109,6 +113,10 @@ const PostcodeSearchModal = _ref2 => {
   // 검색이 실행된 검색어. 입력 중에는 갱신되지 않는다.
   // 초기값은 마운트 시점의 searchQuery — 사용처가 검색어를 채운 채로 열면 그 검색은 이미 실행된 것으로 본다.
   const [searchedQuery, setSearchedQuery] = useState(searchQuery);
+  // 검색어 길이 검사에 걸렸을 때의 오류코드. 사용처 errorCode 보다 앞선다.
+  // 사용처가 결과를 지우지 않아도 이 값이 있는 동안 목록을 숨긴다(늦게 온 응답 포함).
+  const [validationErrorCode, setValidationErrorCode] = useState();
+  const activeErrorCode = validationErrorCode ?? errorCode;
   // Modal 은 닫혀도 이 컴포넌트를 언마운트하지 않아 내부 상태가 다음 열기까지 남는다.
   // 열리는 순간 이전 세션의 선택·검색 상태를 지운다.
   // biome-ignore lint/correctness/useExhaustiveDependencies: searchQuery 를 deps 에 넣으면 입력할 때마다 초기화된다
@@ -116,8 +124,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;
@@ -130,6 +139,11 @@ const PostcodeSearchModal = _ref2 => {
     onSearchQueryChange(event.target.value);
   };
   const handleSearch = () => {
+    if (isSearchQueryTooShort(searchQuery)) {
+      setValidationErrorCode('E0008');
+      return;
+    }
+    setValidationErrorCode(undefined);
     setSearchedQuery(searchQuery);
     onSearch();
   };
@@ -170,7 +184,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
             }), _jsx(Button, {
               className: "ncua-postcode-search-modal__search-button",
               label: SEARCH_BUTTON_LABEL,

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

@@ -617,4 +617,131 @@ describe('PostcodeSearchModal — 검색 영역 고정 표시', () => {
     // Then: 고정할 대상이 없으므로 클래스는 붙지 않는다
     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);
+  });
 });

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);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ncds/ui-admin",
-  "version": "1.8.28-alpha.4",
+  "version": "1.8.28-alpha.5",
   "description": "nhn-commerce의 어드민 디자인 시스템입니다.",
   "scripts": {
     "barrel": "node barrel.js",