@ncds/ui-admin 1.8.21-alpha.0 → 1.8.21-alpha.10

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

@@ -0,0 +1,623 @@
+"use strict";
+
+var _react = require("react");
+var _client = require("react-dom/client");
+var _testUtils = require("react-dom/test-utils");
+var _vitest = require("vitest");
+var _PostcodeSearchModal = require("../PostcodeSearchModal");
+// @vitest-environment jsdom
+
+// React 18에서 act() 사용 시 필요한 플래그 (미설정 시 console.error 경고 발생)
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+const PAGE_SIZE = 15;
+/** 한 페이지에 다 들어가는 결과 건수 — Tip 카드 미노출 케이스 */
+const SMALL_RESULT_COUNT = 5;
+/** SMALL_RESULT_COUNT 기준 총 페이지 수 */
+const SMALL_RESULT_TOTAL_PAGE = 1;
+/** 여러 페이지로 나뉘는 결과 건수 — totalPage(3) <= 페이지 그룹 크기(10) */
+const LARGE_RESULT_COUNT = 45;
+/** LARGE_RESULT_COUNT 기준 총 페이지 수 */
+const LARGE_RESULT_TOTAL_PAGE = 3;
+/** 점프 버튼이 뜨는 결과 건수 — totalPage(14) > 페이지 그룹 크기(10) */
+const HUGE_RESULT_COUNT = 200;
+/** 클릭 대상 페이지 번호 */
+const TARGET_PAGE = 3;
+/** 본문을 아래로 내린 상태를 흉내 낼 scrollTop 값 */
+const SCROLLED_OFFSET = 120;
+/** 맨 위로 되돌린 scrollTop 값 */
+const SCROLL_TOP = 0;
+/** 결과 더미 생성 기준값 */
+const ZIP_CODE_BASE = 13529;
+const ROAD_NUMBER_BASE = 242;
+const JIBUN_NUMBER_BASE = 620;
+let root = null;
+let container = null;
+/**
+ * Modal 은 createPortal 로 document.body 에 붙으므로 조회 기준은 body 다.
+ */
+function render(props) {
+  if (!container) {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = (0, _client.createRoot)(container);
+  }
+  (0, _testUtils.act)(() => {
+    root?.render(/*#__PURE__*/(0, _react.createElement)(_PostcodeSearchModal.PostcodeSearchModal, props));
+  });
+  return document.body;
+}
+/** matchMedia 를 vitest 환경에서 stub 한다 (jsdom 은 matches 를 항상 false 로 준다). */
+function stubMatchMedia(matches) {
+  _vitest.vi.stubGlobal('matchMedia', query => ({
+    matches,
+    media: query,
+    onchange: null,
+    addEventListener: _vitest.vi.fn(),
+    removeEventListener: _vitest.vi.fn(),
+    addListener: _vitest.vi.fn(),
+    removeListener: _vitest.vi.fn(),
+    dispatchEvent: _vitest.vi.fn(() => false)
+  }));
+}
+/**
+ * controlled input 에 값을 입력한다.
+ * React 는 element 의 value 프로퍼티를 가로채 변경을 추적하므로, 프로토타입의 네이티브 setter 를
+ * 직접 호출해야 React 가 "값이 바뀌었다"고 판단하고 onChange 를 발화한다.
+ */
+function setInputValue(input, value) {
+  const nativeSetter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value')?.set;
+  if (!nativeSetter) throw new Error('HTMLInputElement.value setter 를 찾을 수 없습니다');
+  (0, _testUtils.act)(() => {
+    nativeSetter.call(input, value);
+    input.dispatchEvent(new Event('input', {
+      bubbles: true
+    }));
+  });
+}
+function makeResults(count) {
+  return Array.from({
+    length: count
+  }, (_, i) => ({
+    zipCode: String(ZIP_CODE_BASE + i),
+    roadAddress: `경기 성남시 분당구 판교로 ${ROAD_NUMBER_BASE + i}`,
+    jibunAddress: `경기 성남시 분당구 삼평동 ${JIBUN_NUMBER_BASE + i}`
+  }));
+}
+function baseProps() {
+  let overrides = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  return {
+    open: true,
+    onClose: _vitest.vi.fn(),
+    searchQuery: '',
+    onSearchQueryChange: _vitest.vi.fn(),
+    onSearch: _vitest.vi.fn(),
+    results: [],
+    totalCount: 0,
+    currentPage: 1,
+    onPageChange: _vitest.vi.fn(),
+    onSelect: _vitest.vi.fn(),
+    ...overrides
+  };
+}
+const tipOf = el => el.querySelector('.ncua-postcode-search-modal__tip');
+const searchAreaOf = el => el.querySelector('.ncua-postcode-search-modal__search-area');
+const isFixedSearchArea = el => Boolean(searchAreaOf(el)?.classList.contains('is-fixed'));
+const scrollerOf = el => el.querySelector('.ncua-modal__content');
+/** jsdom 은 레이아웃이 없어 scrollTop 이 항상 0 이므로, 값을 덮어쓰고 scroll 이벤트를 쏜다. */
+function scrollContent(el, scrollTop) {
+  const scroller = scrollerOf(el);
+  if (!scroller) throw new Error('모달 본문 스크롤 컨테이너를 찾을 수 없습니다');
+  Object.defineProperty(scroller, 'scrollTop', {
+    value: scrollTop,
+    configurable: true
+  });
+  (0, _testUtils.act)(() => {
+    scroller.dispatchEvent(new Event('scroll'));
+  });
+}
+const resultTitleOf = el => el.querySelector('.ncua-postcode-search-modal__result-title');
+const resultDescOf = el => el.querySelector('.ncua-postcode-search-modal__result-desc');
+const countLabelOf = el => el.querySelector('.ncua-postcode-search-modal__count');
+const itemsOf = el => el.querySelectorAll('.ncua-postcode-search-modal__item');
+const inputRootOf = el => el.querySelector('.ncua-input');
+const hintOf = el => el.querySelector('.ncua-input__hint-text');
+const emptyStateOf = el => el.querySelector('.ncua-empty-state');
+const paginationOf = el => el.querySelector('.ncua-pagination');
+(0, _vitest.beforeEach)(() => {
+  stubMatchMedia(false);
+});
+(0, _vitest.afterEach)(() => {
+  if (root && container) {
+    (0, _testUtils.act)(() => root?.unmount());
+    container.remove();
+  }
+  root = null;
+  container = null;
+  _vitest.vi.unstubAllGlobals();
+});
+(0, _vitest.describe)('PostcodeSearchModal — Case 1: 검색 전 초기 상태', () => {
+  (0, _vitest.it)('Tip 카드만 노출되고 카운트·리스트·페이지네이션·EmptyState 는 렌더되지 않는다', () => {
+    // Given: 검색어·결과가 비어 있고 에러도 없는 상태에서
+    // When: 모달을 열면
+    const el = render(baseProps());
+    // Then: Tip 카드만 노출되고 결과 영역은 전부 미노출이다
+    (0, _vitest.expect)(tipOf(el)).not.toBeNull();
+    (0, _vitest.expect)(resultTitleOf(el)).toBeNull();
+    (0, _vitest.expect)(countLabelOf(el)).toBeNull();
+    (0, _vitest.expect)(el.querySelector('.ncua-postcode-search-modal__list')).toBeNull();
+    (0, _vitest.expect)(paginationOf(el)).toBeNull();
+    (0, _vitest.expect)(emptyStateOf(el)).toBeNull();
+  });
+  (0, _vitest.it)('검색 인풋이 비어 있고 destructive 상태가 아니다', () => {
+    // Given/When: 초기 상태로 렌더하면
+    const el = render(baseProps());
+    // Then: 입력값이 비어 있고 오류 스타일이 아니다
+    const input = el.querySelector('.ncua-input input');
+    (0, _vitest.expect)(input?.value).toBe('');
+    (0, _vitest.expect)(inputRootOf(el)?.classList.contains('destructive')).toBe(false);
+    (0, _vitest.expect)(hintOf(el)).toBeNull();
+  });
+  (0, _vitest.it)('open=false 면 아무것도 렌더되지 않는다', () => {
+    // Given/When: 닫힌 상태로 렌더하면
+    const el = render(baseProps({
+      open: false
+    }));
+    // Then: 모달 자체가 없다
+    (0, _vitest.expect)(el.querySelector('.ncua-modal')).toBeNull();
+  });
+});
+(0, _vitest.describe)('PostcodeSearchModal — Case 2~4: 에러코드별 hint 매핑', () => {
+  _vitest.it.each([['E0008', '서', '검색어를 두 글자 이상 입력해주세요.'], ['E0006', '서울특별시', '시도명으로는 검색이 불가합니다.'], ['E0011', '!!!', '검색어를 다시 입력해주세요.'], ['E0009', '!!!', '검색어를 다시 입력해주세요.'], ['E0010', '!!!', '검색어를 다시 입력해주세요.'], ['E0012', '!!!', '검색어를 다시 입력해주세요.'], ['E0013', '!!!', '검색어를 다시 입력해주세요.']])('%s 이면 destructive 와 hint "%s" 가 노출된다', (errorCode, searchQuery, hint) => {
+    // Given/When: 에러코드를 전달해 렌더하면
+    const el = render(baseProps({
+      searchQuery,
+      errorCode
+    }));
+    // Then: Input 이 destructive 이고 매핑된 hint 문구가 나온다
+    (0, _vitest.expect)(inputRootOf(el)?.classList.contains('destructive')).toBe(true);
+    (0, _vitest.expect)(hintOf(el)?.textContent).toBe(hint);
+  });
+  (0, _vitest.it)('에러 상태에서는 Tip 카드가 노출되고 리스트·EmptyState 는 미노출이다', () => {
+    // Given/When: 에러코드를 전달해 렌더하면
+    const el = render(baseProps({
+      searchQuery: '서',
+      errorCode: 'E0008'
+    }));
+    // Then: Tip 카드만 남는다
+    (0, _vitest.expect)(tipOf(el)).not.toBeNull();
+    (0, _vitest.expect)(resultTitleOf(el)).toBeNull();
+    (0, _vitest.expect)(el.querySelector('.ncua-postcode-search-modal__list')).toBeNull();
+    (0, _vitest.expect)(emptyStateOf(el)).toBeNull();
+    (0, _vitest.expect)(paginationOf(el)).toBeNull();
+  });
+});
+(0, _vitest.describe)('PostcodeSearchModal — Case 5: 검색 결과 없음', () => {
+  (0, _vitest.it)('검색 실행 전 입력만 한 상태에서는 EmptyState 가 노출되지 않는다', () => {
+    // Given: 검색어가 빈 상태로 열려 있다가
+    render(baseProps({
+      searchQuery: '',
+      results: [],
+      totalCount: 0
+    }));
+    // When: 검색을 실행하지 않고 글자만 입력하면
+    const el = render(baseProps({
+      searchQuery: '존재하지않는주소',
+      results: [],
+      totalCount: 0
+    }));
+    // Then: "검색 결과가 없습니다." 는 뜨지 않고 Tip 카드만 유지된다
+    (0, _vitest.expect)(emptyStateOf(el)).toBeNull();
+    (0, _vitest.expect)(tipOf(el)).not.toBeNull();
+  });
+  (0, _vitest.it)('EmptyState 가 "검색 결과가 없습니다." 로 렌더되고 Tip 카드가 유지된다', () => {
+    // Given: 검색어는 있으나 결과가 0건인 상태에서
+    const el = render(baseProps({
+      searchQuery: '존재하지않는주소',
+      results: [],
+      totalCount: 0
+    }));
+    // When: 검색 버튼을 눌러 실제로 검색을 실행하면
+    (0, _testUtils.act)(() => {
+      el.querySelector('.ncua-postcode-search-modal__search-button')?.click();
+    });
+    // Then: EmptyState 가 노출되고 오류 스타일은 아니며 페이지네이션은 없다
+    (0, _vitest.expect)(emptyStateOf(el)?.textContent).toContain('검색 결과가 없습니다.');
+    (0, _vitest.expect)(tipOf(el)).not.toBeNull();
+    (0, _vitest.expect)(resultTitleOf(el)).toBeNull();
+    (0, _vitest.expect)(inputRootOf(el)?.classList.contains('destructive')).toBe(false);
+    (0, _vitest.expect)(paginationOf(el)).toBeNull();
+    (0, _vitest.expect)(countLabelOf(el)).toBeNull();
+  });
+});
+(0, _vitest.describe)('PostcodeSearchModal — Case 6: 결과 있음', () => {
+  (0, _vitest.it)('카운트 "검색 5개" 와 5행 리스트가 렌더되고 Tip 카드는 미노출된다', () => {
+    // Given/When: 5건 결과를 전달하면
+    const results = makeResults(SMALL_RESULT_COUNT);
+    const el = render(baseProps({
+      searchQuery: '판교로',
+      results,
+      totalCount: SMALL_RESULT_COUNT
+    }));
+    // Then: 카운트·리스트가 노출되고 Tip 카드는 사라진다
+    (0, _vitest.expect)(countLabelOf(el)?.textContent).toBe(`검색 ${SMALL_RESULT_COUNT}개`);
+    (0, _vitest.expect)(itemsOf(el)).toHaveLength(SMALL_RESULT_COUNT);
+    (0, _vitest.expect)(tipOf(el)).toBeNull();
+  });
+  (0, _vitest.it)('각 행에 라디오·도로명·우편번호·지번이 모두 렌더된다', () => {
+    // Given/When: 5건 결과를 전달하면
+    const results = makeResults(SMALL_RESULT_COUNT);
+    const el = render(baseProps({
+      searchQuery: '판교로',
+      results,
+      totalCount: SMALL_RESULT_COUNT
+    }));
+    // Then: 첫 행의 구성요소가 설계대로 존재한다
+    const first = itemsOf(el)[0];
+    (0, _vitest.expect)(first.querySelector('input[type="radio"]')).not.toBeNull();
+    (0, _vitest.expect)(first.querySelector('.ncua-postcode-search-modal__item-road')?.textContent).toBe(results[0].roadAddress);
+    (0, _vitest.expect)(first.querySelector('.ncua-postcode-search-modal__item-zip')?.textContent).toBe(results[0].zipCode);
+    (0, _vitest.expect)(first.querySelector('.ncua-postcode-search-modal__item-jibun')?.textContent).toBe(results[0].jibunAddress);
+    // 도로명·지번 두 줄과 각 줄의 배지
+    (0, _vitest.expect)(first.querySelectorAll('.ncua-postcode-search-modal__addr-line')).toHaveLength(2);
+    (0, _vitest.expect)(first.querySelectorAll('.ncua-postcode-search-modal__badge')).toHaveLength(2);
+  });
+  (0, _vitest.it)('totalPage=1 이면 점프 버튼 없이 페이지 번호만 노출된다', () => {
+    // Given/When: 5건(1페이지) 결과를 전달하면
+    const el = render(baseProps({
+      searchQuery: '판교로',
+      results: makeResults(SMALL_RESULT_COUNT),
+      totalCount: SMALL_RESULT_COUNT
+    }));
+    // Then: 점프 버튼이 없다
+    (0, _vitest.expect)(paginationOf(el)).not.toBeNull();
+    (0, _vitest.expect)(el.querySelector('.ncua-pagination__first')).toBeNull();
+    (0, _vitest.expect)(el.querySelector('.ncua-pagination__last')).toBeNull();
+    (0, _vitest.expect)(el.querySelectorAll('.ncua-pagination__page-num')).toHaveLength(SMALL_RESULT_TOTAL_PAGE);
+  });
+});
+(0, _vitest.describe)('PostcodeSearchModal — Case 7: 결과 여러 페이지', () => {
+  (0, _vitest.it)('카운트 "검색 45개" 와 15행 리스트가 렌더되고 Tip 카드 대신 결과 안내 문구가 남는다', () => {
+    // Given/When: 45건 중 첫 페이지 15건을 전달하면
+    const el = render(baseProps({
+      searchQuery: '판교로',
+      results: makeResults(PAGE_SIZE),
+      totalCount: LARGE_RESULT_COUNT
+    }));
+    // Then: Tip 카드는 사라지고 검색 영역의 안내 문구(제목·조합)가 남는다
+    (0, _vitest.expect)(countLabelOf(el)?.textContent).toBe(`검색 ${LARGE_RESULT_COUNT}개`);
+    (0, _vitest.expect)(itemsOf(el)).toHaveLength(PAGE_SIZE);
+    (0, _vitest.expect)(tipOf(el)).toBeNull();
+    (0, _vitest.expect)(resultTitleOf(el)?.textContent).toBe('아래 조합으로 검색하면 원하는 주소를 더 쉽게 찾을 수 있어요.');
+    (0, _vitest.expect)(resultDescOf(el)?.textContent).toBe('도로명+건물번호, 지역명+지번, 지역명+건물명(아파트명)');
+  });
+  (0, _vitest.it)('검색 인풋과 안내 문구가 같은 고정 영역 안에 묶이고 결과 목록은 그 밖에 있다', () => {
+    // Given/When: 결과가 여러 페이지인 상태로 렌더하면
+    const el = render(baseProps({
+      searchQuery: '판교로',
+      results: makeResults(PAGE_SIZE),
+      totalCount: LARGE_RESULT_COUNT
+    }));
+    // Then: 상단 고정 영역이 인풋 행과 안내 문구를 함께 감싸고, 스크롤되는 목록은 밖에 남는다
+    const searchArea = searchAreaOf(el);
+    (0, _vitest.expect)(searchArea?.querySelector('.ncua-postcode-search-modal__search')).not.toBeNull();
+    (0, _vitest.expect)(searchArea?.querySelector('.ncua-postcode-search-modal__result-title')).not.toBeNull();
+    (0, _vitest.expect)(searchArea?.querySelector('.ncua-postcode-search-modal__result-desc')).not.toBeNull();
+    (0, _vitest.expect)(searchArea?.querySelector('.ncua-postcode-search-modal__list')).toBeNull();
+  });
+  (0, _vitest.it)('totalPage(3) 가 PAGER_WINDOW(10) 이하이므로 점프 버튼은 노출되지 않는다', () => {
+    // Given/When: totalCount=45, PAGE_SIZE=15 → totalPage=3
+    const el = render(baseProps({
+      searchQuery: '판교로',
+      results: makeResults(PAGE_SIZE),
+      totalCount: LARGE_RESULT_COUNT
+    }));
+    // Then: 페이지 번호 3개만 노출된다
+    (0, _vitest.expect)(el.querySelectorAll('.ncua-pagination__page-num')).toHaveLength(LARGE_RESULT_TOTAL_PAGE);
+    (0, _vitest.expect)(el.querySelector('.ncua-pagination__first')).toBeNull();
+  });
+});
+(0, _vitest.describe)('PostcodeSearchModal — Case 8: 결과 대량', () => {
+  (0, _vitest.it)('totalCount=200 이면 첫/이전/다음/마지막 점프 버튼이 노출된다', () => {
+    // Given/When: totalCount=200 → totalPage=14 > PAGER_WINDOW(10)
+    const el = render(baseProps({
+      searchQuery: '판교로',
+      results: makeResults(PAGE_SIZE),
+      totalCount: HUGE_RESULT_COUNT
+    }));
+    // Then: 점프 버튼 4종이 모두 존재한다
+    (0, _vitest.expect)(el.querySelector('.ncua-pagination__first')).not.toBeNull();
+    (0, _vitest.expect)(el.querySelector('.ncua-pagination__before')).not.toBeNull();
+    (0, _vitest.expect)(el.querySelector('.ncua-pagination__next')).not.toBeNull();
+    (0, _vitest.expect)(el.querySelector('.ncua-pagination__last')).not.toBeNull();
+    (0, _vitest.expect)(tipOf(el)).toBeNull();
+    (0, _vitest.expect)(resultTitleOf(el)).not.toBeNull();
+  });
+  (0, _vitest.it)('3페이지 버튼을 클릭하면 onPageChange(3) 이 호출된다', () => {
+    // Given: 대량 결과가 렌더된 상태에서
+    const onPageChange = _vitest.vi.fn();
+    const el = render(baseProps({
+      searchQuery: '판교로',
+      results: makeResults(PAGE_SIZE),
+      totalCount: HUGE_RESULT_COUNT,
+      onPageChange
+    }));
+    // When: 3번 페이지 버튼을 클릭하면
+    const pageButtons = el.querySelectorAll('.ncua-pagination__page-num');
+    (0, _testUtils.act)(() => {
+      pageButtons[TARGET_PAGE - 1]?.click();
+    });
+    // Then: 3 이 전달된다
+    (0, _vitest.expect)(onPageChange).toHaveBeenCalledWith(TARGET_PAGE);
+  });
+});
+(0, _vitest.describe)('PostcodeSearchModal — 아이템 선택', () => {
+  (0, _vitest.it)('라디오를 클릭하면 해당 결과로 onSelect 가 호출된다', () => {
+    // Given: 5건 결과가 렌더된 상태에서
+    const results = makeResults(SMALL_RESULT_COUNT);
+    const onSelect = _vitest.vi.fn();
+    const el = render(baseProps({
+      searchQuery: '판교로',
+      results,
+      totalCount: SMALL_RESULT_COUNT,
+      onSelect
+    }));
+    // When: 2번째 아이템의 라디오를 클릭하면
+    const radios = el.querySelectorAll('.ncua-postcode-search-modal__item input[type="radio"]');
+    (0, _testUtils.act)(() => {
+      radios[1]?.click();
+    });
+    // Then: 2번째 결과 객체가 전달된다
+    (0, _vitest.expect)(onSelect).toHaveBeenCalledWith(results[1]);
+  });
+  (0, _vitest.it)('loading 중에는 결과가 0건이어도 EmptyState 가 뜨지 않는다', () => {
+    // Given: 검색을 실행해 EmptyState 가 떠 있는 상태에서
+    render(baseProps({
+      searchQuery: '판교로',
+      results: [],
+      totalCount: 0
+    }));
+    (0, _testUtils.act)(() => {
+      document.body.querySelector('.ncua-postcode-search-modal__search-button')?.click();
+    });
+    // When: 사용처가 API 응답을 기다린다고 알리면
+    const el = render(baseProps({
+      searchQuery: '판교로',
+      results: [],
+      totalCount: 0,
+      loading: true
+    }));
+    // Then: "검색 결과가 없습니다." 는 노출되지 않는다
+    (0, _vitest.expect)(emptyStateOf(el)).toBeNull();
+  });
+  (0, _vitest.it)('모달을 다시 열면 이전 선택과 검색 상태가 초기화된다', () => {
+    // Given: 결과에서 한 행을 고른 뒤
+    const results = makeResults(SMALL_RESULT_COUNT);
+    const el = render(baseProps({
+      searchQuery: '판교로',
+      results,
+      totalCount: SMALL_RESULT_COUNT
+    }));
+    const radios = el.querySelectorAll('.ncua-postcode-search-modal__item input[type="radio"]');
+    (0, _testUtils.act)(() => {
+      radios[1]?.click();
+    });
+    (0, _vitest.expect)(radios[1].checked).toBe(true);
+    // When: 모달을 닫았다가 다시 열면
+    render(baseProps({
+      open: false,
+      searchQuery: '판교로',
+      results,
+      totalCount: SMALL_RESULT_COUNT
+    }));
+    const reopened = render(baseProps({
+      searchQuery: '판교로',
+      results,
+      totalCount: SMALL_RESULT_COUNT
+    }));
+    // Then: 선택 표시가 남아 있지 않다
+    const reopenedRadios = reopened.querySelectorAll('.ncua-postcode-search-modal__item input[type="radio"]');
+    (0, _vitest.expect)(reopenedRadios[1].checked).toBe(false);
+  });
+  (0, _vitest.it)('클릭한 행만 checked 로 표시된다 — 사용처가 값을 되돌려주지 않아도 된다', () => {
+    // Given: 결과 5건이 렌더된 상태에서
+    const results = makeResults(SMALL_RESULT_COUNT);
+    const el = render(baseProps({
+      searchQuery: '판교로',
+      results,
+      totalCount: SMALL_RESULT_COUNT
+    }));
+    const radios = el.querySelectorAll('.ncua-postcode-search-modal__item input[type="radio"]');
+    // When: 두 번째 행을 클릭하면
+    (0, _testUtils.act)(() => {
+      radios[1]?.click();
+    });
+    // Then: 그 행만 checked 다
+    (0, _vitest.expect)(radios[0].checked).toBe(false);
+    (0, _vitest.expect)(radios[1].checked).toBe(true);
+    (0, _vitest.expect)(radios[2].checked).toBe(false);
+  });
+  (0, _vitest.it)('우편번호가 같은 행이 있어도 클릭한 행만 checked 다', () => {
+    // Given: 같은 우편번호를 쓰는 두 행이 한 페이지에 있을 때
+    const sameZip = '13529';
+    const results = [{
+      zipCode: sameZip,
+      roadAddress: '경기 성남시 분당구 판교로 242',
+      jibunAddress: '경기 성남시 분당구 삼평동 620'
+    }, {
+      zipCode: sameZip,
+      roadAddress: '경기 성남시 분당구 판교로 242',
+      jibunAddress: '경기 성남시 분당구 삼평동 621'
+    }];
+    const el = render(baseProps({
+      searchQuery: '판교로',
+      results,
+      totalCount: results.length
+    }));
+    const radios = el.querySelectorAll('.ncua-postcode-search-modal__item input[type="radio"]');
+    // When: 두 번째 행을 클릭하면
+    (0, _testUtils.act)(() => {
+      radios[1]?.click();
+    });
+    // Then: 첫 행은 선택되지 않는다
+    (0, _vitest.expect)(radios[0].checked).toBe(false);
+    (0, _vitest.expect)(radios[1].checked).toBe(true);
+  });
+});
+(0, _vitest.describe)('PostcodeSearchModal — 검색 인터랙션', () => {
+  (0, _vitest.it)('검색 버튼을 누르면 onSearch 가 호출된다', () => {
+    // Given: 검색어가 입력된 상태에서
+    const onSearch = _vitest.vi.fn();
+    const el = render(baseProps({
+      searchQuery: '판교로',
+      onSearch
+    }));
+    // When: 인풋 바깥 오른쪽의 검색 버튼을 클릭하면
+    const searchButton = el.querySelector('.ncua-postcode-search-modal__search-button');
+    (0, _vitest.expect)(searchButton?.textContent).toBe('검색');
+    (0, _testUtils.act)(() => {
+      searchButton?.click();
+    });
+    // Then: onSearch 가 호출된다
+    (0, _vitest.expect)(onSearch).toHaveBeenCalledTimes(1);
+  });
+  (0, _vitest.it)('Enter 를 누르면 onSearch 가 호출된다', () => {
+    // Given: 검색어가 입력된 상태에서
+    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: 검색 버튼을 누른 것과 동일하게 onSearch 가 호출된다
+    (0, _vitest.expect)(onSearch).toHaveBeenCalledTimes(1);
+  });
+  (0, _vitest.it)('한글 조합 중 Enter 는 검색으로 보지 않는다', () => {
+    // Given: 검색어를 조합 중인 상태에서
+    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',
+        isComposing: true,
+        bubbles: true
+      }));
+    });
+    // Then: 검색은 실행되지 않는다
+    (0, _vitest.expect)(onSearch).not.toHaveBeenCalled();
+  });
+  (0, _vitest.it)('입력값이 바뀌면 onSearchQueryChange 에 새 값이 전달된다', () => {
+    // Given: controlled 인풋이 렌더된 상태에서
+    const onSearchQueryChange = _vitest.vi.fn();
+    const el = render(baseProps({
+      onSearchQueryChange
+    }));
+    // When: 값을 입력하면
+    const input = el.querySelector('.ncua-input input');
+    if (!input) throw new Error('검색 인풋이 렌더되지 않았습니다');
+    // controlled input 은 React 의 value tracker 를 거치므로, 네이티브 setter 로 값을 넣어야
+    // React 가 변경을 감지해 onChange 를 발화한다.
+    setInputValue(input, '판교로');
+    // Then: 새 값이 전달된다
+    (0, _vitest.expect)(onSearchQueryChange).toHaveBeenCalledWith('판교로');
+  });
+});
+(0, _vitest.describe)('PostcodeSearchModal — 반응형 전환', () => {
+  (0, _vitest.it)('데스크톱(768px 초과) 에서는 Pagination 이 pc 모드로 렌더된다', () => {
+    // Given/When: matchMedia 가 매치되지 않는 환경에서 렌더하면
+    stubMatchMedia(false);
+    const el = render(baseProps({
+      searchQuery: '판교로',
+      results: makeResults(SMALL_RESULT_COUNT),
+      totalCount: SMALL_RESULT_COUNT
+    }));
+    // Then: pc 모디파이어가 붙는다
+    (0, _vitest.expect)(paginationOf(el)?.classList.contains('ncua-pagination--pc')).toBe(true);
+  });
+  (0, _vitest.it)('모바일(768px 이하) 에서는 Pagination 이 mo 모드로 렌더된다', () => {
+    // Given/When: 640px 상당으로 matchMedia 가 매치되는 환경에서 렌더하면
+    stubMatchMedia(true);
+    const el = render(baseProps({
+      searchQuery: '판교로',
+      results: makeResults(SMALL_RESULT_COUNT),
+      totalCount: SMALL_RESULT_COUNT
+    }));
+    // Then: mo 모디파이어가 붙는다
+    (0, _vitest.expect)(paginationOf(el)?.classList.contains('ncua-pagination--mo')).toBe(true);
+  });
+});
+(0, _vitest.describe)('PostcodeSearchModal.Tip — 서브컴포넌트', () => {
+  (0, _vitest.it)('조합 3종과 예시 주소를 모두 보여준다', () => {
+    // Given/When: Tip 카드가 노출되는 초기 상태로 렌더하면
+    const el = render(baseProps());
+    // Then: 안내 문구와 3개 조합, 예시 주소가 모두 포함된다
+    const tipText = tipOf(el)?.textContent ?? '';
+    (0, _vitest.expect)(tipText).toContain('아래 조합으로 검색하면 원하는 주소를 더 쉽게 찾을 수 있어요.');
+    (0, _vitest.expect)(tipText).toContain('도로명 + 건물번호');
+    (0, _vitest.expect)(tipText).toContain('예) 디지털로26길 43');
+    (0, _vitest.expect)(tipText).toContain('지역명(동·리) + 번지');
+    (0, _vitest.expect)(tipText).toContain('예) 구로동 235-3');
+    (0, _vitest.expect)(tipText).toContain('지역명(동·리) + 건물명(아파트명)');
+    (0, _vitest.expect)(tipText).toContain('예) 구로동 대륭포스트타워8차');
+  });
+  (0, _vitest.it)('Tip 아이콘은 하드코딩 SVG 가 아니라 아이콘 슬롯 클래스로 렌더된다', () => {
+    // Given/When: Tip 카드를 렌더하면
+    const el = render(baseProps());
+    // Then: 지정한 아이콘 클래스를 가진 svg 가 존재한다
+    (0, _vitest.expect)(tipOf(el)?.querySelector('svg.ncua-postcode-search-modal__tip-icon')).not.toBeNull();
+  });
+  (0, _vitest.it)('PostcodeSearchModal.Tip 이 compound 서브컴포넌트로 노출된다', () => {
+    // Given/When/Then: displayName 규약을 만족한다
+    (0, _vitest.expect)(typeof _PostcodeSearchModal.PostcodeSearchModal.Tip).toBe('function');
+    (0, _vitest.expect)(_PostcodeSearchModal.PostcodeSearchModal.Tip.displayName).toBe('PostcodeSearchModal.Tip');
+  });
+});
+(0, _vitest.describe)('PostcodeSearchModal — 검색 영역 고정 표시', () => {
+  (0, _vitest.it)('결과가 있어도 스크롤하기 전에는 is-fixed 가 붙지 않는다', () => {
+    // Given/When: 결과를 스크롤하지 않은 상태로 렌더하면
+    const el = render(baseProps({
+      searchQuery: '판교로',
+      results: makeResults(PAGE_SIZE),
+      totalCount: LARGE_RESULT_COUNT
+    }));
+    // Then: 검색 영역이 아직 떠 있지 않으므로 경계선 클래스도 없다
+    (0, _vitest.expect)(isFixedSearchArea(el)).toBe(false);
+  });
+  (0, _vitest.it)('결과를 스크롤하면 is-fixed 가 붙고, 맨 위로 돌아오면 다시 사라진다', () => {
+    // Given: 결과가 렌더된 상태에서
+    const el = render(baseProps({
+      searchQuery: '판교로',
+      results: makeResults(PAGE_SIZE),
+      totalCount: LARGE_RESULT_COUNT
+    }));
+    // When: 본문을 아래로 스크롤하면
+    scrollContent(el, SCROLLED_OFFSET);
+    // Then: 경계선 클래스가 붙는다
+    (0, _vitest.expect)(isFixedSearchArea(el)).toBe(true);
+    // When: 다시 맨 위로 올리면
+    scrollContent(el, SCROLL_TOP);
+    // Then: 경계선 클래스가 사라진다
+    (0, _vitest.expect)(isFixedSearchArea(el)).toBe(false);
+  });
+  (0, _vitest.it)('결과가 없으면 스크롤이 일어나도 is-fixed 가 붙지 않는다', () => {
+    // Given: 초기 상태(결과 없음)로 렌더하고
+    const el = render(baseProps());
+    // When: 본문 스크롤 이벤트가 들어와도
+    scrollContent(el, SCROLLED_OFFSET);
+    // Then: 고정할 대상이 없으므로 클래스는 붙지 않는다
+    (0, _vitest.expect)(isFixedSearchArea(el)).toBe(false);
+  });
+});

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

@@ -0,0 +1,16 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+var _PostcodeSearchModal = require("./PostcodeSearchModal");
+Object.keys(_PostcodeSearchModal).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _PostcodeSearchModal[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _PostcodeSearchModal[key];
+    }
+  });
+});