@ncds/ui-admin 1.8.21-alpha.5 → 1.8.21-alpha.7

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

@@ -0,0 +1,118 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { AnnotationInfoFill } from '@ncds/ui-admin-icon';
+import classnames from 'classnames';
+import { useEffect, useState } from 'react';
+import { Button } from '../../action/button';
+import { EmptyState } from '../../feedback-and-status/empty-state';
+import { InputBase } from '../../forms-and-input/input-base';
+import { Radio } from '../../forms-and-input/radio';
+import { Pagination } from '../../navigation/pagination';
+import { Modal } from '../modal';
+/** 기획서 기준값 */
+const PAGE_SIZE = 15;
+/** 페이지 번호 그룹 크기 — 초과 시 Pagination 이 점프 버튼을 노출한다 */
+const PAGER_WINDOW = 10;
+/** 이 건수를 넘으면 Tip 을 압축 버전으로 전환한다 (기획서 기준) */
+const TIP_COMPACT_THRESHOLD = 30;
+/** 반응형 전환 기준 — assets/styles/base/_variable.scss 의 $breakpoint 와 동일 */
+const MOBILE_BREAKPOINT = 768;
+const MODAL_TITLE = '주소 찾기';
+const SEARCH_PLACEHOLDER = '도로명, 지번, 건물명 검색';
+const SEARCH_BUTTON_LABEL = '검색';
+const EMPTY_TITLE = '검색 결과가 없습니다.';
+const EMPTY_DESCRIPTION = '검색어를 다시 확인해 주세요.';
+const ROAD_BADGE_LABEL = '도로명';
+const JIBUN_BADGE_LABEL = '지번';
+const TIP_LABEL = 'Tip';
+// 라디오 그룹 이름. `ncua-` 로 시작하면 MCP 의 BEM 추출기가 CSS 클래스로 오인하므로 접두사를 뺀다.
+const RESULT_RADIO_NAME = 'postcode-search-modal-result';
+/** E0006·E0008 외 나머지 코드는 모두 같은 문구를 쓴다(기획서: E0009~E0013 통합). */
+const DEFAULT_ERROR_HINT = '검색어를 다시 입력해주세요.';
+const ERROR_HINT = {
+    E0006: '시도명으로는 검색이 불가합니다.',
+    E0008: '검색어를 두 글자 이상 입력해주세요.',
+};
+/** Tip 카드 첫 줄 안내 문구 (기획서 TIPS.searchTitle) */
+const TIP_TITLE = '아래 조합으로 검색하면 원하는 주소를 더 쉽게 찾을 수 있어요.';
+/** Tip 상세 버전에 노출할 검색어 조합과 예시 주소 (기획서 TIPS.searchTips) */
+const TIP_ITEMS = [
+    { combination: '도로명 + 건물번호', example: '디지털로26길 43' },
+    { combination: '지역명(동·리) + 번지', example: '구로동 235-3' },
+    { combination: '지역명(동·리) + 건물명(아파트명)', example: '구로동 대륭포스트타워8차' },
+];
+/** Tip 압축 버전 문구 — 예시 주소를 빼고 조합만 한 줄로 (기획서 TIPS.searchTipsCompact) */
+const TIP_COMPACT_TEXT = "'도로명+건물번호', '지역명+지번', '지역명+건물명(아파트명)'";
+const TIP_EXAMPLE_PREFIX = '예)';
+const TIP_ICON_SIZE = 16;
+/** 선택 표시를 판정하는 키. 우편번호만으로는 같은 건물의 다른 지번을 구분하지 못한다. */
+const resultKey = ({ zipCode, roadAddress, jibunAddress }) => `${zipCode}|${roadAddress}|${jibunAddress}`;
+const resolveTipVariant = (hasResults, totalCount) => {
+    if (!hasResults)
+        return 'detail';
+    return totalCount > TIP_COMPACT_THRESHOLD ? 'compact' : null;
+};
+/** SSR(도큐사우루스 등)에서는 초기값을 false(=PC)로 두고 mount 이후 갱신한다. */
+const useIsMobileViewport = () => {
+    const [isMobile, setIsMobile] = useState(false);
+    useEffect(() => {
+        if (typeof window === 'undefined' || typeof window.matchMedia !== 'function')
+            return;
+        const mediaQuery = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT}px)`);
+        const sync = () => setIsMobile(mediaQuery.matches);
+        sync();
+        mediaQuery.addEventListener('change', sync);
+        return () => {
+            mediaQuery.removeEventListener('change', sync);
+        };
+    }, []);
+    return isMobile;
+};
+const Tip = ({ compact = false, className }) => {
+    return (_jsxs("div", { className: classnames('ncua-postcode-search-modal__tip', className), children: [!compact && (_jsxs("p", { className: "ncua-postcode-search-modal__tip-label", children: [_jsx(AnnotationInfoFill, { className: "ncua-postcode-search-modal__tip-icon", width: TIP_ICON_SIZE, height: TIP_ICON_SIZE }), TIP_LABEL] })), _jsx("p", { className: "ncua-postcode-search-modal__tip-title", children: TIP_TITLE }), compact ? (_jsx("p", { className: "ncua-postcode-search-modal__tip-compact-text", children: TIP_COMPACT_TEXT })) : (_jsx("ul", { className: "ncua-postcode-search-modal__tip-list", children: TIP_ITEMS.map(({ combination, example }) => (_jsxs("li", { className: "ncua-postcode-search-modal__tip-item", children: [_jsx("span", { className: "ncua-postcode-search-modal__tip-combination", children: combination }), _jsx("span", { className: "ncua-postcode-search-modal__tip-example", children: `${TIP_EXAMPLE_PREFIX} ${example}` })] }, combination))) }))] }));
+};
+Tip.displayName = 'PostcodeSearchModal.Tip';
+const PostcodeSearchModal = ({ open, onClose, zIndex, className, searchQuery, onSearchQueryChange, onSearch, results, totalCount, currentPage, onPageChange, pageSize = PAGE_SIZE, loading = false, errorCode, onSelect, }) => {
+    const isMobile = useIsMobileViewport();
+    // 선택 표시는 컴포넌트가 직접 들고 있는다. 사용처는 onSelect 로 값만 받으면 된다.
+    // 우편번호는 한 페이지에 중복될 수 있어 주소 전체를 키로 쓴다.
+    const [selectedKey, setSelectedKey] = useState();
+    // 검색이 실행된 검색어. 입력 중에는 갱신되지 않는다.
+    // 초기값은 마운트 시점의 searchQuery — 사용처가 검색어를 채운 채로 열면 그 검색은 이미 실행된 것으로 본다.
+    const [searchedQuery, setSearchedQuery] = useState(searchQuery);
+    // Modal 은 닫혀도 이 컴포넌트를 언마운트하지 않아 내부 상태가 다음 열기까지 남는다.
+    // 열리는 순간 이전 세션의 선택·검색 상태를 지운다.
+    // biome-ignore lint/correctness/useExhaustiveDependencies: searchQuery 를 deps 에 넣으면 입력할 때마다 초기화된다
+    useEffect(() => {
+        if (!open)
+            return;
+        setSelectedKey(undefined);
+        setSearchedQuery(searchQuery);
+    }, [open]);
+    const hasError = Boolean(errorCode);
+    const hasResults = !hasError && results.length > 0;
+    // 검색을 실행한 검색어와 현재 입력값이 같을 때만 "결과 없음"으로 본다.
+    // 입력 중에는 두 값이 달라지고, 응답을 기다리는 동안에는 loading 이 막는다.
+    const showEmptyState = !hasError && !loading && results.length === 0 && searchQuery !== '' && searchQuery === searchedQuery;
+    const tipVariant = resolveTipVariant(hasResults, totalCount);
+    const handleSearchQueryChange = (event) => {
+        onSearchQueryChange(event.target.value);
+    };
+    const handleSearch = () => {
+        setSearchedQuery(searchQuery);
+        onSearch();
+    };
+    const handleSearchKeyDown = (event) => {
+        // 한글 조합 중의 Enter 는 글자 확정이므로 검색으로 보지 않는다.
+        if (event.key !== 'Enter' || event.nativeEvent.isComposing)
+            return;
+        event.preventDefault();
+        handleSearch();
+    };
+    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", 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, 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 })] }), tipVariant && _jsx(PostcodeSearchModal.Tip, { compact: tipVariant === 'compact' }), 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 }) }))] }) })] }));
+};
+PostcodeSearchModal.displayName = 'PostcodeSearchModal';
+PostcodeSearchModal.Tip = Tip;
+export { PostcodeSearchModal };

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

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

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

@@ -0,0 +1,456 @@
+// @vitest-environment 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';
+import { PostcodeSearchModal } from '../PostcodeSearchModal';
+// React 18에서 act() 사용 시 필요한 플래그 (미설정 시 console.error 경고 발생)
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+const PAGE_SIZE = 15;
+/** Tip 압축 임계값(30) 이하 결과 건수 — Tip 미노출 케이스 */
+const SMALL_RESULT_COUNT = 5;
+/** SMALL_RESULT_COUNT 기준 총 페이지 수 */
+const SMALL_RESULT_TOTAL_PAGE = 1;
+/** Tip 압축 임계값(30) 초과 결과 건수 — Tip 압축 + 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;
+/** 결과 더미 생성 기준값 */
+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 = createRoot(container);
+    }
+    act(() => {
+        root?.render(createElement(PostcodeSearchModal, props));
+    });
+    return document.body;
+}
+/** matchMedia 를 vitest 환경에서 stub 한다 (jsdom 은 matches 를 항상 false 로 준다). */
+function stubMatchMedia(matches) {
+    vi.stubGlobal('matchMedia', (query) => ({
+        matches,
+        media: query,
+        onchange: null,
+        addEventListener: vi.fn(),
+        removeEventListener: vi.fn(),
+        addListener: vi.fn(),
+        removeListener: vi.fn(),
+        dispatchEvent: 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 를 찾을 수 없습니다');
+    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(overrides = {}) {
+    return {
+        open: true,
+        onClose: vi.fn(),
+        searchQuery: '',
+        onSearchQueryChange: vi.fn(),
+        onSearch: vi.fn(),
+        results: [],
+        totalCount: 0,
+        currentPage: 1,
+        onPageChange: vi.fn(),
+        onSelect: vi.fn(),
+        ...overrides,
+    };
+}
+const tipOf = (el) => el.querySelector('.ncua-postcode-search-modal__tip');
+const isCompactTip = (el) => Boolean(el.querySelector('.ncua-postcode-search-modal__tip-compact-text'));
+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');
+beforeEach(() => {
+    stubMatchMedia(false);
+});
+afterEach(() => {
+    if (root && container) {
+        act(() => root?.unmount());
+        container.remove();
+    }
+    root = null;
+    container = null;
+    vi.unstubAllGlobals();
+});
+describe('PostcodeSearchModal — Case 1: 검색 전 초기 상태', () => {
+    it('상세 Tip 만 노출되고 카운트·리스트·페이지네이션·EmptyState 는 렌더되지 않는다', () => {
+        // Given: 검색어·결과가 비어 있고 에러도 없는 상태에서
+        // When: 모달을 열면
+        const el = render(baseProps());
+        // Then: 상세 Tip 만 노출되고 결과 영역은 전부 미노출이다
+        expect(tipOf(el)).not.toBeNull();
+        expect(isCompactTip(el)).toBe(false);
+        expect(countLabelOf(el)).toBeNull();
+        expect(el.querySelector('.ncua-postcode-search-modal__list')).toBeNull();
+        expect(paginationOf(el)).toBeNull();
+        expect(emptyStateOf(el)).toBeNull();
+    });
+    it('검색 인풋이 비어 있고 destructive 상태가 아니다', () => {
+        // Given/When: 초기 상태로 렌더하면
+        const el = render(baseProps());
+        // Then: 입력값이 비어 있고 오류 스타일이 아니다
+        const input = el.querySelector('.ncua-input input');
+        expect(input?.value).toBe('');
+        expect(inputRootOf(el)?.classList.contains('destructive')).toBe(false);
+        expect(hintOf(el)).toBeNull();
+    });
+    it('open=false 면 아무것도 렌더되지 않는다', () => {
+        // Given/When: 닫힌 상태로 렌더하면
+        const el = render(baseProps({ open: false }));
+        // Then: 모달 자체가 없다
+        expect(el.querySelector('.ncua-modal')).toBeNull();
+    });
+});
+describe('PostcodeSearchModal — Case 2~4: 에러코드별 hint 매핑', () => {
+    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 문구가 나온다
+        expect(inputRootOf(el)?.classList.contains('destructive')).toBe(true);
+        expect(hintOf(el)?.textContent).toBe(hint);
+    });
+    it('에러 상태에서는 상세 Tip 이 노출되고 리스트·EmptyState 는 미노출이다', () => {
+        // Given/When: 에러코드를 전달해 렌더하면
+        const el = render(baseProps({ searchQuery: '서', errorCode: 'E0008' }));
+        // Then: 상세 Tip 만 남는다
+        expect(tipOf(el)).not.toBeNull();
+        expect(isCompactTip(el)).toBe(false);
+        expect(el.querySelector('.ncua-postcode-search-modal__list')).toBeNull();
+        expect(emptyStateOf(el)).toBeNull();
+        expect(paginationOf(el)).toBeNull();
+    });
+});
+describe('PostcodeSearchModal — Case 5: 검색 결과 없음', () => {
+    it('검색 실행 전 입력만 한 상태에서는 EmptyState 가 노출되지 않는다', () => {
+        // Given: 검색어가 빈 상태로 열려 있다가
+        render(baseProps({ searchQuery: '', results: [], totalCount: 0 }));
+        // When: 검색을 실행하지 않고 글자만 입력하면
+        const el = render(baseProps({ searchQuery: '존재하지않는주소', results: [], totalCount: 0 }));
+        // Then: "검색 결과가 없습니다." 는 뜨지 않고 상세 Tip 만 유지된다
+        expect(emptyStateOf(el)).toBeNull();
+        expect(tipOf(el)).not.toBeNull();
+    });
+    it('EmptyState 가 "검색 결과가 없습니다." 로 렌더되고 상세 Tip 이 유지된다', () => {
+        // Given: 검색어는 있으나 결과가 0건인 상태에서
+        const el = render(baseProps({ searchQuery: '존재하지않는주소', results: [], totalCount: 0 }));
+        // When: 검색 버튼을 눌러 실제로 검색을 실행하면
+        act(() => {
+            el.querySelector('.ncua-postcode-search-modal__search-button')?.click();
+        });
+        // Then: EmptyState 가 노출되고 오류 스타일은 아니며 페이지네이션은 없다
+        expect(emptyStateOf(el)?.textContent).toContain('검색 결과가 없습니다.');
+        expect(tipOf(el)).not.toBeNull();
+        expect(isCompactTip(el)).toBe(false);
+        expect(inputRootOf(el)?.classList.contains('destructive')).toBe(false);
+        expect(paginationOf(el)).toBeNull();
+        expect(countLabelOf(el)).toBeNull();
+    });
+});
+describe('PostcodeSearchModal — Case 6: 결과 30건 이하', () => {
+    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 은 사라진다
+        expect(countLabelOf(el)?.textContent).toBe(`검색 ${SMALL_RESULT_COUNT}개`);
+        expect(itemsOf(el)).toHaveLength(SMALL_RESULT_COUNT);
+        expect(tipOf(el)).toBeNull();
+    });
+    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];
+        expect(first.querySelector('input[type="radio"]')).not.toBeNull();
+        expect(first.querySelector('.ncua-postcode-search-modal__item-road')?.textContent).toBe(results[0].roadAddress);
+        expect(first.querySelector('.ncua-postcode-search-modal__item-zip')?.textContent).toBe(results[0].zipCode);
+        expect(first.querySelector('.ncua-postcode-search-modal__item-jibun')?.textContent).toBe(results[0].jibunAddress);
+        // 도로명·지번 두 줄과 각 줄의 배지
+        expect(first.querySelectorAll('.ncua-postcode-search-modal__addr-line')).toHaveLength(2);
+        expect(first.querySelectorAll('.ncua-postcode-search-modal__badge')).toHaveLength(2);
+    });
+    it('totalPage=1 이면 점프 버튼 없이 페이지 번호만 노출된다', () => {
+        // Given/When: 5건(1페이지) 결과를 전달하면
+        const el = render(baseProps({ searchQuery: '판교로', results: makeResults(SMALL_RESULT_COUNT), totalCount: SMALL_RESULT_COUNT }));
+        // Then: 점프 버튼이 없다
+        expect(paginationOf(el)).not.toBeNull();
+        expect(el.querySelector('.ncua-pagination__first')).toBeNull();
+        expect(el.querySelector('.ncua-pagination__last')).toBeNull();
+        expect(el.querySelectorAll('.ncua-pagination__page-num')).toHaveLength(SMALL_RESULT_TOTAL_PAGE);
+    });
+});
+describe('PostcodeSearchModal — Case 7: 결과 30건 초과', () => {
+    it('카운트 "검색 45개" 와 15행 리스트, 압축 Tip 이 렌더된다', () => {
+        // Given/When: 45건 중 첫 페이지 15건을 전달하면
+        const el = render(baseProps({ searchQuery: '판교로', results: makeResults(PAGE_SIZE), totalCount: LARGE_RESULT_COUNT }));
+        // Then: 압축 Tip 이 노출된다
+        expect(countLabelOf(el)?.textContent).toBe(`검색 ${LARGE_RESULT_COUNT}개`);
+        expect(itemsOf(el)).toHaveLength(PAGE_SIZE);
+        expect(tipOf(el)).not.toBeNull();
+        expect(isCompactTip(el)).toBe(true);
+    });
+    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개만 노출된다
+        expect(el.querySelectorAll('.ncua-pagination__page-num')).toHaveLength(LARGE_RESULT_TOTAL_PAGE);
+        expect(el.querySelector('.ncua-pagination__first')).toBeNull();
+    });
+});
+describe('PostcodeSearchModal — Case 8: 결과 대량', () => {
+    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종이 모두 존재한다
+        expect(el.querySelector('.ncua-pagination__first')).not.toBeNull();
+        expect(el.querySelector('.ncua-pagination__before')).not.toBeNull();
+        expect(el.querySelector('.ncua-pagination__next')).not.toBeNull();
+        expect(el.querySelector('.ncua-pagination__last')).not.toBeNull();
+        expect(isCompactTip(el)).toBe(true);
+    });
+    it('3페이지 버튼을 클릭하면 onPageChange(3) 이 호출된다', () => {
+        // Given: 대량 결과가 렌더된 상태에서
+        const onPageChange = 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');
+        act(() => {
+            pageButtons[TARGET_PAGE - 1]?.click();
+        });
+        // Then: 3 이 전달된다
+        expect(onPageChange).toHaveBeenCalledWith(TARGET_PAGE);
+    });
+});
+describe('PostcodeSearchModal — 아이템 선택', () => {
+    it('라디오를 클릭하면 해당 결과로 onSelect 가 호출된다', () => {
+        // Given: 5건 결과가 렌더된 상태에서
+        const results = makeResults(SMALL_RESULT_COUNT);
+        const onSelect = 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"]');
+        act(() => {
+            radios[1]?.click();
+        });
+        // Then: 2번째 결과 객체가 전달된다
+        expect(onSelect).toHaveBeenCalledWith(results[1]);
+    });
+    it('loading 중에는 결과가 0건이어도 EmptyState 가 뜨지 않는다', () => {
+        // Given: 검색을 실행해 EmptyState 가 떠 있는 상태에서
+        render(baseProps({ searchQuery: '판교로', results: [], totalCount: 0 }));
+        act(() => {
+            document.body.querySelector('.ncua-postcode-search-modal__search-button')?.click();
+        });
+        // When: 사용처가 API 응답을 기다린다고 알리면
+        const el = render(baseProps({ searchQuery: '판교로', results: [], totalCount: 0, loading: true }));
+        // Then: "검색 결과가 없습니다." 는 노출되지 않는다
+        expect(emptyStateOf(el)).toBeNull();
+    });
+    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"]');
+        act(() => {
+            radios[1]?.click();
+        });
+        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"]');
+        expect(reopenedRadios[1].checked).toBe(false);
+    });
+    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: 두 번째 행을 클릭하면
+        act(() => {
+            radios[1]?.click();
+        });
+        // Then: 그 행만 checked 다
+        expect(radios[0].checked).toBe(false);
+        expect(radios[1].checked).toBe(true);
+        expect(radios[2].checked).toBe(false);
+    });
+    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: 두 번째 행을 클릭하면
+        act(() => {
+            radios[1]?.click();
+        });
+        // Then: 첫 행은 선택되지 않는다
+        expect(radios[0].checked).toBe(false);
+        expect(radios[1].checked).toBe(true);
+    });
+});
+describe('PostcodeSearchModal — 검색 인터랙션', () => {
+    it('검색 버튼을 누르면 onSearch 가 호출된다', () => {
+        // Given: 검색어가 입력된 상태에서
+        const onSearch = vi.fn();
+        const el = render(baseProps({ searchQuery: '판교로', onSearch }));
+        // When: 인풋 바깥 오른쪽의 검색 버튼을 클릭하면
+        const searchButton = el.querySelector('.ncua-postcode-search-modal__search-button');
+        expect(searchButton?.textContent).toBe('검색');
+        act(() => {
+            searchButton?.click();
+        });
+        // Then: onSearch 가 호출된다
+        expect(onSearch).toHaveBeenCalledTimes(1);
+    });
+    it('Enter 를 누르면 onSearch 가 호출된다', () => {
+        // Given: 검색어가 입력된 상태에서
+        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: 검색 버튼을 누른 것과 동일하게 onSearch 가 호출된다
+        expect(onSearch).toHaveBeenCalledTimes(1);
+    });
+    it('한글 조합 중 Enter 는 검색으로 보지 않는다', () => {
+        // Given: 검색어를 조합 중인 상태에서
+        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', isComposing: true, bubbles: true }));
+        });
+        // Then: 검색은 실행되지 않는다
+        expect(onSearch).not.toHaveBeenCalled();
+    });
+    it('입력값이 바뀌면 onSearchQueryChange 에 새 값이 전달된다', () => {
+        // Given: controlled 인풋이 렌더된 상태에서
+        const onSearchQueryChange = 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: 새 값이 전달된다
+        expect(onSearchQueryChange).toHaveBeenCalledWith('판교로');
+    });
+});
+describe('PostcodeSearchModal — 반응형 전환', () => {
+    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 모디파이어가 붙는다
+        expect(paginationOf(el)?.classList.contains('ncua-pagination--pc')).toBe(true);
+    });
+    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 모디파이어가 붙는다
+        expect(paginationOf(el)?.classList.contains('ncua-pagination--mo')).toBe(true);
+    });
+});
+describe('PostcodeSearchModal.Tip — 서브컴포넌트', () => {
+    it('상세 모드는 조합 3종과 예시 주소를 모두 보여준다', () => {
+        // Given/When: 상세 Tip 이 노출되는 초기 상태로 렌더하면
+        const el = render(baseProps());
+        // Then: 안내 문구와 3개 조합, 예시 주소가 모두 포함된다
+        const tipText = tipOf(el)?.textContent ?? '';
+        expect(tipText).toContain('아래 조합으로 검색하면 원하는 주소를 더 쉽게 찾을 수 있어요.');
+        expect(tipText).toContain('도로명 + 건물번호');
+        expect(tipText).toContain('예) 디지털로26길 43');
+        expect(tipText).toContain('지역명(동·리) + 번지');
+        expect(tipText).toContain('예) 구로동 235-3');
+        expect(tipText).toContain('지역명(동·리) + 건물명(아파트명)');
+        expect(tipText).toContain('예) 구로동 대륭포스트타워8차');
+    });
+    it('압축 모드는 조합 3종만 보여주고 예시는 생략한다', () => {
+        // Given/When: 30건 초과 결과로 압축 Tip 을 렌더하면
+        const el = render(baseProps({ searchQuery: '판교로', results: makeResults(PAGE_SIZE), totalCount: LARGE_RESULT_COUNT }));
+        // Then: 조합만 한 줄로 남고 예시 주소는 없다
+        const tipText = tipOf(el)?.textContent ?? '';
+        expect(tipText).toContain('아래 조합으로 검색하면 원하는 주소를 더 쉽게 찾을 수 있어요.');
+        expect(tipText).toContain("'도로명+건물번호', '지역명+지번', '지역명+건물명(아파트명)'");
+        expect(tipText).not.toContain('디지털로26길 43');
+        expect(tipText).not.toContain('구로동 235-3');
+        expect(tipText).not.toContain('구로동 대륭포스트타워8차');
+    });
+    it('Tip 아이콘은 하드코딩 SVG 가 아니라 아이콘 슬롯 클래스로 렌더된다', () => {
+        // Given/When: 상세 Tip 을 렌더하면
+        const el = render(baseProps());
+        // Then: 지정한 아이콘 클래스를 가진 svg 가 존재한다
+        expect(tipOf(el)?.querySelector('svg.ncua-postcode-search-modal__tip-icon')).not.toBeNull();
+    });
+    it('PostcodeSearchModal.Tip 이 compound 서브컴포넌트로 노출된다', () => {
+        // Given/When/Then: displayName 규약을 만족한다
+        expect(typeof PostcodeSearchModal.Tip).toBe('function');
+        expect(PostcodeSearchModal.Tip.displayName).toBe('PostcodeSearchModal.Tip');
+    });
+});

package/dist/temp/src/components/overlays/postcode-search-modal/index.d.ts

@@ -0,0 +1 @@
+export * from './PostcodeSearchModal';

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

@@ -0,0 +1 @@
+export * from './PostcodeSearchModal';