@ncds/ui-admin 1.8.21-alpha.1 → 1.8.21-alpha.11

package/dist/temp/src/components/overlays/notification/__tests__/MessageNotification.test.js

@@ -0,0 +1,190 @@
+// @vitest-environment jsdom
+import { createElement } from 'react';
+import { createRoot } from 'react-dom/client';
+import { act } from 'react-dom/test-utils';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { MessageNotification } from '../MessageNotification';
+// React 18에서 act() 사용 시 필요한 플래그 (미설정 시 console.error 경고 발생)
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+const SELECTOR = {
+    ROOT: '.ncua-message-notification',
+    CONTENT: '.ncua-message-notification__content',
+    CONTENT_WRAPPER: '.ncua-message-notification__content-wrapper',
+    ICON: '.ncua-message-notification__icon',
+    ACTIONS_CONTAINER: '.ncua-message-notification__actions-container',
+    ACTIONS: '.ncua-message-notification__actions',
+    FOOTER_CONTAINER: '.ncua-message-notification__footer-container',
+    HIDE_LINK: '.ncua-message-notification__hide-link',
+    CLOSE_BUTTON: '.ncua-message-notification__close-button',
+};
+const mounted = [];
+function renderMessageNotification(props = {}) {
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    const root = createRoot(container);
+    act(() => {
+        root.render(createElement(MessageNotification, { title: '알림 제목', ...props }));
+    });
+    mounted.push({ root, container });
+    return container;
+}
+afterEach(() => {
+    for (const { root, container } of mounted.splice(0)) {
+        act(() => {
+            root.unmount();
+        });
+        container.remove();
+    }
+});
+describe('MessageNotification (React) — DOM 구조 계약', () => {
+    it('U-1: __footer-container가 __actions-container의 자식으로 렌더된다', () => {
+        // Given: 다시 보지 않기·닫기 핸들러가 주어지고
+        // When: MessageNotification을 렌더하면
+        const container = renderMessageNotification({ onHidePermanently: vi.fn(), onClose: vi.fn() });
+        // Then: footer-container는 actions-container의 직계 자식이다 (content의 직계 자식이 아니다)
+        const actionsContainer = container.querySelector(SELECTOR.ACTIONS_CONTAINER);
+        const footerContainer = container.querySelector(SELECTOR.FOOTER_CONTAINER);
+        expect(actionsContainer).not.toBeNull();
+        expect(footerContainer).not.toBeNull();
+        expect(footerContainer?.parentElement).toBe(actionsContainer);
+    });
+    it('U-2: actions 지정 시 __actions와 __footer-container가 __actions-container 안에 순서대로 공존한다', () => {
+        // Given: 액션 버튼 2개와 다시 보지 않기·닫기 핸들러가 주어지고
+        const actions = [
+            { label: '조회하기', hierarchy: 'text', onClick: vi.fn() },
+            { label: '포인트 충전', hierarchy: 'text-gray', onClick: vi.fn() },
+        ];
+        // When: 렌더하면
+        const container = renderMessageNotification({ actions, onHidePermanently: vi.fn(), onClose: vi.fn() });
+        // Then: actions-container의 자식은 [actions, footer-container] 순서다
+        const actionsContainer = container.querySelector(SELECTOR.ACTIONS_CONTAINER);
+        const actionsGroup = container.querySelector(SELECTOR.ACTIONS);
+        const footerContainer = container.querySelector(SELECTOR.FOOTER_CONTAINER);
+        expect(actionsContainer).not.toBeNull();
+        expect(Array.from(actionsContainer?.children ?? [])).toEqual([actionsGroup, footerContainer]);
+    });
+    it('U-3: onHidePermanently·onClose·actions 미지정 시 빈 컨테이너가 남지 않는다', () => {
+        // Given/When: 우측 그룹에 표시할 요소가 하나도 없는 상태로 렌더하면
+        const container = renderMessageNotification();
+        // Then: actions-container도 footer-container도 렌더되지 않는다
+        expect(container.querySelector(SELECTOR.ACTIONS_CONTAINER)).toBeNull();
+        expect(container.querySelector(SELECTOR.FOOTER_CONTAINER)).toBeNull();
+        // 본문 영역은 그대로 유지된다
+        expect(container.querySelector(SELECTOR.CONTENT_WRAPPER)).not.toBeNull();
+    });
+    it('U-3-a: actions만 지정하면 actions-container만 남고 footer-container는 없다', () => {
+        // Given/When: 액션 버튼만 있고 닫기 그룹이 없으면
+        const container = renderMessageNotification({
+            actions: [{ label: '조회하기', hierarchy: 'text', onClick: vi.fn() }],
+        });
+        // Then: actions-container는 존재하고 그 자식은 actions 그룹 하나뿐이다
+        const actionsContainer = container.querySelector(SELECTOR.ACTIONS_CONTAINER);
+        const actionsGroup = container.querySelector(SELECTOR.ACTIONS);
+        expect(actionsContainer).not.toBeNull();
+        expect(container.querySelector(SELECTOR.FOOTER_CONTAINER)).toBeNull();
+        expect(Array.from(actionsContainer?.children ?? [])).toEqual([actionsGroup]);
+    });
+    it('U-3-b: onClose만 지정하면 footer-container에 닫기 버튼만 담긴다', () => {
+        // Given/When: 닫기 핸들러만 지정하면
+        const container = renderMessageNotification({ onClose: vi.fn() });
+        // Then: footer-container에는 닫기 버튼 1개만 존재하고 hide-link는 없다
+        const footerContainer = container.querySelector(SELECTOR.FOOTER_CONTAINER);
+        expect(footerContainer?.children).toHaveLength(1);
+        expect(footerContainer?.querySelector(SELECTOR.CLOSE_BUTTON)).not.toBeNull();
+        expect(footerContainer?.querySelector(SELECTOR.HIDE_LINK)).toBeNull();
+    });
+    it('U-4: FeaturedIcon이 md 사이즈(40px 원 / 20px 아이콘)로 렌더된다', () => {
+        // Given/When: error 색상으로 렌더하면
+        const container = renderMessageNotification({ color: 'error' });
+        // Then: featured-icon은 --md 수식자를 가지며 내부 SVG는 20px다
+        const icon = container.querySelector(SELECTOR.ICON);
+        expect(icon).not.toBeNull();
+        expect(icon?.classList.contains('ncua-featured-icon--md')).toBe(true);
+        expect(icon?.classList.contains('ncua-featured-icon--lg')).toBe(false);
+        expect(icon?.querySelector('svg')?.getAttribute('width')).toBe('20');
+    });
+    it('hide-link는 구현별 수식자(--link/--text) 없이 공통 클래스 2개만 갖는다', () => {
+        // Given/When: 다시 보지 않기 핸들러를 지정해 렌더하면
+        const container = renderMessageNotification({ onHidePermanently: vi.fn() });
+        // Then: SCSS 미정의 수식자 --link에 의존하지 않는다
+        const hideLink = container.querySelector(SELECTOR.HIDE_LINK);
+        expect(hideLink?.className.split(' ').filter(Boolean).sort()).toEqual([
+            'ncua-message-notification__hide-link',
+            'ncua-notification__action-button',
+        ]);
+    });
+});
+describe('MessageNotification (React) — 공개 API 회귀 방지', () => {
+    it('지원하지 않는 color("info")는 neutral로 폴백한다', () => {
+        // Given/When: message 타입이 지원하지 않는 info 색상을 넘기면
+        const container = renderMessageNotification({ color: 'info' });
+        // Then: neutral 수식자로 렌더되고 info 수식자는 없다
+        const root = container.querySelector(SELECTOR.ROOT);
+        expect(root?.classList.contains('ncua-message-notification--neutral')).toBe(true);
+        expect(root?.classList.contains('ncua-message-notification--info')).toBe(false);
+    });
+    it('닫기/다시 보지 않기 클릭 시 핸들러가 호출되고 접근성 속성이 유지된다', () => {
+        // Given: 핸들러를 지정해 렌더하고
+        const onClose = vi.fn();
+        const onHidePermanently = vi.fn();
+        const container = renderMessageNotification({ onClose, onHidePermanently });
+        // When: 각 버튼을 클릭하면
+        act(() => {
+            container.querySelector(SELECTOR.CLOSE_BUTTON)?.click();
+            container.querySelector(SELECTOR.HIDE_LINK)?.click();
+        });
+        // Then: 핸들러가 각각 1회 호출되고 role/aria-label이 유지된다
+        expect(onClose).toHaveBeenCalledTimes(1);
+        expect(onHidePermanently).toHaveBeenCalledTimes(1);
+        expect(container.querySelector(SELECTOR.ROOT)?.getAttribute('role')).toBe('alert');
+        expect(container.querySelector(SELECTOR.CLOSE_BUTTON)?.getAttribute('aria-label')).toBe('알림 닫기');
+    });
+});
+describe('MessageNotification (React) — 액션 버튼 색상(hierarchy)', () => {
+    const SIZE_MODIFIER = /^ncua-btn--(xs|sm|md|lg|xl)$/;
+    /** 사이즈를 제외한 `ncua-btn--*` 수식자 = 색상(hierarchy) 수식자. */
+    function buttonHierarchyModifiers(root) {
+        return Array.from(root.querySelectorAll('.ncua-btn')).map((button) => Array.from(button.classList).find((name) => name.startsWith('ncua-btn--') && !SIZE_MODIFIER.test(name)) ?? '');
+    }
+    it('Figma TO-BE 조합(secondary-gray / secondary)을 ncua-btn 수식자로 반영한다', () => {
+        // Given/When: 조회하기 secondary-gray, 포인트 충전 secondary로 렌더하면
+        const container = renderMessageNotification({
+            actions: [
+                { label: '조회하기', hierarchy: 'secondary-gray', onClick: vi.fn() },
+                { label: '포인트 충전', hierarchy: 'secondary', onClick: vi.fn() },
+            ],
+        });
+        // Then: ButtonTheme와 동일한 수식자가 순서대로 붙는다
+        expect(buttonHierarchyModifiers(container)).toEqual(['ncua-btn--secondary-gray', 'ncua-btn--secondary']);
+    });
+    it('text / text-gray도 계속 지원한다', () => {
+        // Given/When: 기존 어휘로 렌더하면
+        const container = renderMessageNotification({
+            actions: [
+                { label: '조회하기', hierarchy: 'text', onClick: vi.fn() },
+                { label: '포인트 충전', hierarchy: 'text-gray', onClick: vi.fn() },
+            ],
+        });
+        // Then: 기존 수식자가 그대로 유지된다 (회귀 방지)
+        expect(buttonHierarchyModifiers(container)).toEqual(['ncua-btn--text', 'ncua-btn--text-gray']);
+    });
+    it('hierarchy를 생략하면 기본값 text로 렌더한다', () => {
+        // Given/When: 색상을 지정하지 않은 액션을 렌더하면
+        const container = renderMessageNotification({ actions: [{ label: '확인', onClick: vi.fn() }] });
+        // Then: Button의 기본값(secondary-gray)이 아니라 알림의 기본값 text가 적용된다
+        expect(buttonHierarchyModifiers(container)).toEqual(['ncua-btn--text']);
+    });
+    it('액션 버튼 클릭 시 onClick이 호출된다', () => {
+        // Given: secondary 색상 액션을 렌더하고
+        const onClick = vi.fn();
+        const container = renderMessageNotification({
+            actions: [{ label: '포인트 충전', hierarchy: 'secondary', onClick }],
+        });
+        // When: 버튼을 클릭하면
+        act(() => {
+            container.querySelector('.ncua-btn')?.click();
+        });
+        // Then: 핸들러가 1회 호출된다
+        expect(onClick).toHaveBeenCalledTimes(1);
+    });
+});

package/dist/temp/src/components/overlays/notification/__tests__/hidePermanentlyLabel.test.d.ts

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

package/dist/temp/src/components/overlays/notification/__tests__/hidePermanentlyLabel.test.js

@@ -0,0 +1,160 @@
+// @vitest-environment jsdom
+import { createElement } from 'react';
+import { createRoot } from 'react-dom/client';
+import { act } from 'react-dom/test-utils';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { FullWidthNotification } from '../FullWidthNotification';
+import { MessageNotification } from '../MessageNotification';
+import { Notification } from '../Notification';
+// React 18에서 act() 사용 시 필요한 플래그 (미설정 시 console.error 경고 발생)
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+const SELECTOR = {
+    /** message 타입 — 고도몰이 textContent 덮어쓰기에 쓰는 하위호환 계약 선택자. */
+    MESSAGE_HIDE_LINK: '.ncua-message-notification__hide-link',
+    /** full-width 타입 — 다시보지 않기 버튼. */
+    FULL_WIDTH_LINK: '.ncua-full-width-notification__link',
+    ACTION_BUTTON: '.ncua-notification__action-button',
+};
+/** 각 타입의 현행 기본 문구. 표기 통일은 별도 결정 사항이므로 서로 다른 값을 그대로 유지한다. */
+const DEFAULT_LABEL = {
+    MESSAGE: '다시 보지 않기',
+    FULL_WIDTH: '다시보지 않기',
+};
+const mounted = [];
+function render(element) {
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    const root = createRoot(container);
+    act(() => {
+        root.render(element);
+    });
+    mounted.push({ root, container });
+    return container;
+}
+function renderMessage(props = {}) {
+    return render(createElement(MessageNotification, { title: '알림 제목', ...props }));
+}
+function renderFullWidth(props = {}) {
+    return render(createElement(FullWidthNotification, { title: '알림 제목', ...props }));
+}
+function renderNotification(props = {}) {
+    return render(createElement(Notification, { title: '알림 제목', ...props }));
+}
+afterEach(() => {
+    for (const { root, container } of mounted.splice(0)) {
+        act(() => {
+            root.unmount();
+        });
+        container.remove();
+    }
+});
+describe('hidePermanentlyLabel (React) — message 타입', () => {
+    it('R-1: prop 미지정 시 기본 문구 "다시 보지 않기"가 렌더된다', () => {
+        // Given: hidePermanentlyLabel 없이 onHidePermanently만 주어지고
+        // When: MessageNotification을 렌더하면
+        const container = renderMessage({ onHidePermanently: vi.fn() });
+        // Then: 현행 기본 문구가 그대로 노출된다 (시각적 변화 0)
+        const hideLink = container.querySelector(SELECTOR.MESSAGE_HIDE_LINK);
+        expect(hideLink?.textContent).toBe(DEFAULT_LABEL.MESSAGE);
+    });
+    it('R-2: prop 지정 시 그 값이 렌더된다', () => {
+        // Given: 커스텀 라벨이 주어지고
+        // When: 렌더하면
+        const container = renderMessage({ onHidePermanently: vi.fn(), hidePermanentlyLabel: '30일간 보지 않기' });
+        // Then: 하드코딩 문구 대신 전달한 값이 노출된다
+        const hideLink = container.querySelector(SELECTOR.MESSAGE_HIDE_LINK);
+        expect(hideLink?.textContent).toBe('30일간 보지 않기');
+    });
+    it('R-3: ReactNode 라벨을 받아 엘리먼트로 렌더한다', () => {
+        // Given: 문자열이 아닌 ReactNode 라벨이 주어지고
+        const label = createElement('span', { className: 'custom-hide-label' }, '커스텀 노드');
+        // When: 렌더하면
+        const container = renderMessage({ onHidePermanently: vi.fn(), hidePermanentlyLabel: label });
+        // Then: 노드가 hide-link 내부에 그대로 마운트된다
+        const hideLink = container.querySelector(SELECTOR.MESSAGE_HIDE_LINK);
+        expect(hideLink?.querySelector('.custom-hide-label')?.textContent).toBe('커스텀 노드');
+    });
+    it('R-4: 라벨을 바꿔도 __hide-link 클래스 계약이 유지된다', () => {
+        // Given: 커스텀 라벨이 주어지고
+        // When: 렌더하면
+        const container = renderMessage({ onHidePermanently: vi.fn(), hidePermanentlyLabel: '커스텀' });
+        // Then: 고도몰의 textContent 덮어쓰기가 계속 동작하도록 기존 클래스가 모두 남는다
+        const hideLink = container.querySelector(SELECTOR.MESSAGE_HIDE_LINK);
+        expect(hideLink).not.toBeNull();
+        expect(hideLink?.classList.contains('ncua-notification__action-button')).toBe(true);
+        expect(hideLink?.classList.contains('ncua-message-notification__hide-link')).toBe(true);
+    });
+    it('R-5: onHidePermanently 없이 라벨만 주면 버튼이 렌더되지 않는다', () => {
+        // Given: 핸들러 없이 라벨만 주어지고
+        // When: 렌더하면
+        const container = renderMessage({ hidePermanentlyLabel: '커스텀' });
+        // Then: 라벨만으로는 버튼이 생기지 않는다 (핸들러가 렌더 조건)
+        expect(container.querySelector(SELECTOR.MESSAGE_HIDE_LINK)).toBeNull();
+    });
+    it('R-6: 라벨이 DOM 속성으로 새어나가지 않는다', () => {
+        // Given: 커스텀 라벨이 주어지고
+        // When: 렌더하면
+        const container = renderMessage({ onHidePermanently: vi.fn(), hidePermanentlyLabel: '커스텀' });
+        // Then: rest 스프레드를 타고 루트 div의 속성으로 흘러들지 않는다
+        const root = container.querySelector('.ncua-message-notification');
+        expect(root?.hasAttribute('hidepermanentlylabel')).toBe(false);
+    });
+});
+describe('hidePermanentlyLabel (React) — full-width 타입', () => {
+    it('R-7: prop 미지정 시 기본 문구 "다시보지 않기"가 렌더된다', () => {
+        // Given: hidePermanentlyLabel 없이 onHidePermanently만 주어지고
+        // When: FullWidthNotification을 렌더하면
+        const container = renderFullWidth({ onHidePermanently: vi.fn() });
+        // Then: message 타입과 다른 현행 문구가 그대로 유지된다 (표기 통일은 별도 결정)
+        const hideButton = container.querySelector(SELECTOR.FULL_WIDTH_LINK);
+        expect(hideButton?.textContent).toBe(DEFAULT_LABEL.FULL_WIDTH);
+    });
+    it('R-8: prop 지정 시 그 값이 렌더된다', () => {
+        // Given: 커스텀 라벨이 주어지고
+        // When: 렌더하면
+        const container = renderFullWidth({ onHidePermanently: vi.fn(), hidePermanentlyLabel: '오늘 하루 보지 않기' });
+        // Then: 전달한 값이 노출된다
+        const hideButton = container.querySelector(SELECTOR.FULL_WIDTH_LINK);
+        expect(hideButton?.textContent).toBe('오늘 하루 보지 않기');
+    });
+    it('R-9: 라벨을 바꿔도 기존 클래스 계약이 유지된다', () => {
+        // Given: 커스텀 라벨이 주어지고
+        // When: 렌더하면
+        const container = renderFullWidth({ onHidePermanently: vi.fn(), hidePermanentlyLabel: '커스텀' });
+        // Then: 액션 버튼 클래스가 그대로 남는다
+        const hideButton = container.querySelector(SELECTOR.FULL_WIDTH_LINK);
+        expect(hideButton?.classList.contains('ncua-notification__action-button')).toBe(true);
+        expect(hideButton?.classList.contains('ncua-notification__action-button--text')).toBe(true);
+    });
+    it('R-10: onHidePermanently 없이 라벨만 주면 버튼이 렌더되지 않는다', () => {
+        // Given: 핸들러 없이 라벨만 주어지고
+        // When: 렌더하면
+        const container = renderFullWidth({ hidePermanentlyLabel: '커스텀' });
+        // Then: 액션 버튼이 생기지 않는다
+        expect(container.querySelector(SELECTOR.ACTION_BUTTON)).toBeNull();
+    });
+});
+describe('hidePermanentlyLabel (React) — Notification 공유 Props 경유', () => {
+    it('R-11: type="message"에서 공유 Props의 라벨이 전달된다', () => {
+        // Given: 공유 Notification props로 라벨이 주어지고
+        // When: type="message"로 렌더하면
+        const container = renderNotification({
+            type: 'message',
+            onHidePermanently: vi.fn(),
+            hidePermanentlyLabel: '공유 프롭 라벨',
+        });
+        // Then: message 구현까지 라벨이 도달한다
+        expect(container.querySelector(SELECTOR.MESSAGE_HIDE_LINK)?.textContent).toBe('공유 프롭 라벨');
+    });
+    it('R-12: type="full-width"에서 공유 Props의 라벨이 전달된다', () => {
+        // Given: 공유 Notification props로 라벨이 주어지고
+        // When: type="full-width"로 렌더하면
+        const container = renderNotification({
+            type: 'full-width',
+            onHidePermanently: vi.fn(),
+            hidePermanentlyLabel: '공유 프롭 라벨',
+        });
+        // Then: full-width 구현까지 라벨이 도달한다
+        expect(container.querySelector(SELECTOR.FULL_WIDTH_LINK)?.textContent).toBe('공유 프롭 라벨');
+    });
+});

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

@@ -0,0 +1,45 @@
+import { type PostcodeSearchModalTipProps } from './PostcodeSearchModalTip';
+/** 검색 결과 아이템 하나. */
+interface PostcodeSearchResult {
+    /** 우편번호(5자리) */
+    zipCode: string;
+    /** 도로명주소(도로명 + 건물번호 + 참고항목 등) */
+    roadAddress: string;
+    /** 지번주소 */
+    jibunAddress: string;
+}
+/**
+ * 컴포넌트가 표시할 수 있는 에러코드(행정안전부 도로명주소 API 기준).
+ * 기획서에 직접 적힌 코드는 E0006·E0008·E0009·E0012·E0013 이고,
+ * E0010·E0011 은 기획서의 "E0009~E0013 통합" 범위 표기에서 채운 값이다.
+ */
+type PostcodeSearchErrorCode = 'E0006' | 'E0008' | 'E0009' | 'E0010' | 'E0011' | 'E0012' | 'E0013';
+interface PostcodeSearchModalProps {
+    open: boolean;
+    onClose: () => void;
+    zIndex?: number;
+    className?: string;
+    searchQuery: string;
+    onSearchQueryChange: (value: string) => void;
+    onSearch: () => void;
+    results: PostcodeSearchResult[];
+    totalCount: number;
+    currentPage: number;
+    onPageChange: (page: number) => void;
+    /** 페이지당 아이템 수. 기획서 기본값 15 */
+    pageSize?: number;
+    /** 검색 API 응답을 기다리는 중인지 여부. 응답 전에 "결과 없음" 이 먼저 뜨는 것을 막는다. */
+    loading?: boolean;
+    errorCode?: PostcodeSearchErrorCode;
+    onSelect: (result: PostcodeSearchResult) => void;
+}
+declare const PostcodeSearchModal: {
+    ({ open, onClose, zIndex, className, searchQuery, onSearchQueryChange, onSearch, results, totalCount, currentPage, onPageChange, pageSize, loading, errorCode, onSelect, }: PostcodeSearchModalProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+    Tip: {
+        ({ className }: PostcodeSearchModalTipProps): import("react/jsx-runtime").JSX.Element;
+        displayName: string;
+    };
+};
+export { PostcodeSearchModal };
+export type { PostcodeSearchErrorCode, PostcodeSearchModalProps, PostcodeSearchModalTipProps, PostcodeSearchResult };

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

@@ -0,0 +1,125 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import classnames from 'classnames';
+import { useEffect, useRef, 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';
+import { Tip } from './PostcodeSearchModalTip';
+/** 기획서 기준값 */
+const PAGE_SIZE = 15;
+/** 페이지 번호 그룹 크기 — 초과 시 Pagination 이 점프 버튼을 노출한다 */
+const PAGER_WINDOW = 10;
+/** 반응형 전환 기준 — assets/styles/base/_variable.scss 의 $breakpoint 와 동일 */
+const MOBILE_BREAKPOINT = 768;
+/** 본문 스크롤 컨테이너. Modal.Content 가 overflow-y:auto 를 갖는다. */
+const SCROLL_CONTAINER_SELECTOR = '.ncua-modal__content';
+const MODAL_TITLE = '주소 찾기';
+const SEARCH_PLACEHOLDER = '도로명, 지번, 건물명 검색';
+const SEARCH_BUTTON_LABEL = '검색';
+const EMPTY_TITLE = '검색 결과가 없습니다.';
+const EMPTY_DESCRIPTION = '검색어를 다시 확인해 주세요.';
+const ROAD_BADGE_LABEL = '도로명';
+const JIBUN_BADGE_LABEL = '지번';
+// 라디오 그룹 이름. `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: '검색어를 두 글자 이상 입력해주세요.',
+};
+/** 선택 표시를 판정하는 키. 우편번호만으로는 같은 건물의 다른 지번을 구분하지 못한다. */
+const resultKey = ({ zipCode, roadAddress, jibunAddress }) => `${zipCode}|${roadAddress}|${jibunAddress}`;
+/** 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;
+};
+/**
+ * 본문이 위로 스크롤됐는지 여부.
+ * 고정된 검색 영역과 스크롤되는 결과 사이의 경계선을 스크롤 중에만 그리기 위해 쓴다.
+ * enabled 가 false 면 감시를 걸지 않고 항상 false 를 돌려준다.
+ */
+const useIsContentScrolled = (rootRef, enabled) => {
+    const [isScrolled, setIsScrolled] = useState(false);
+    useEffect(() => {
+        if (!enabled) {
+            setIsScrolled(false);
+            return;
+        }
+        const scroller = rootRef.current?.closest(SCROLL_CONTAINER_SELECTOR);
+        if (!scroller)
+            return;
+        const sync = () => setIsScrolled(scroller.scrollTop > 0);
+        // 결과가 바뀌어도 스크롤 위치는 남을 수 있어 구독 시점의 값으로 먼저 맞춘다.
+        sync();
+        scroller.addEventListener('scroll', sync, { passive: true });
+        return () => {
+            scroller.removeEventListener('scroll', sync);
+        };
+    }, [rootRef, enabled]);
+    return isScrolled;
+};
+const PostcodeSearchModal = ({ open, onClose, zIndex, className, searchQuery, onSearchQueryChange, onSearch, results, totalCount, currentPage, onPageChange, pageSize = PAGE_SIZE, loading = false, errorCode, onSelect, }) => {
+    const isMobile = useIsMobileViewport();
+    const rootRef = useRef(null);
+    // 선택 표시는 컴포넌트가 직접 들고 있는다. 사용처는 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 isContentScrolled = useIsContentScrolled(rootRef, open && hasResults);
+    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", 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, 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 })] }), hasResults && (_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 }) }))] }) })] }));
+};
+PostcodeSearchModal.displayName = 'PostcodeSearchModal';
+PostcodeSearchModal.Tip = Tip;
+export { PostcodeSearchModal };

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

@@ -0,0 +1,16 @@
+interface PostcodeSearchModalTipProps {
+    className?: string;
+}
+/** Tip 카드 첫 줄 안내 문구 (기획서 TIPS.searchTitle) */
+declare const TIP_TITLE = "\uC544\uB798 \uC870\uD569\uC73C\uB85C \uAC80\uC0C9\uD558\uBA74 \uC6D0\uD558\uB294 \uC8FC\uC18C\uB97C \uB354 \uC27D\uAC8C \uCC3E\uC744 \uC218 \uC788\uC5B4\uC694.";
+/**
+ * 검색어 조합을 안내하는 Tip 카드.
+ * 결과 목록이 없는 화면(초기·오류·결과 없음)에서만 노출된다.
+ * 결과가 있을 때는 모달이 안내 문구 한 줄만 검색 영역에 붙여 고정한다.
+ */
+declare const Tip: {
+    ({ className }: PostcodeSearchModalTipProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+export { Tip, TIP_TITLE };
+export type { PostcodeSearchModalTipProps };

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

@@ -0,0 +1,24 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { AnnotationInfoFill } from '@ncds/ui-admin-icon';
+import classnames from 'classnames';
+const TIP_LABEL = 'Tip';
+/** Tip 카드 첫 줄 안내 문구 (기획서 TIPS.searchTitle) */
+const TIP_TITLE = '아래 조합으로 검색하면 원하는 주소를 더 쉽게 찾을 수 있어요.';
+/** Tip 에 노출할 검색어 조합과 예시 주소 (기획서 TIPS.searchTips) */
+const TIP_ITEMS = [
+    { combination: '도로명 + 건물번호', example: '디지털로26길 43' },
+    { combination: '지역명(동·리) + 번지', example: '구로동 235-3' },
+    { combination: '지역명(동·리) + 건물명(아파트명)', example: '구로동 대륭포스트타워8차' },
+];
+const TIP_EXAMPLE_PREFIX = '예)';
+const TIP_ICON_SIZE = 16;
+/**
+ * 검색어 조합을 안내하는 Tip 카드.
+ * 결과 목록이 없는 화면(초기·오류·결과 없음)에서만 노출된다.
+ * 결과가 있을 때는 모달이 안내 문구 한 줄만 검색 영역에 붙여 고정한다.
+ */
+const Tip = ({ className }) => {
+    return (_jsxs("div", { className: classnames('ncua-postcode-search-modal__tip', className), children: [_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 }), _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", { children: combination }), _jsx("span", { children: `${TIP_EXAMPLE_PREFIX} ${example}` })] }, combination))) })] }));
+};
+Tip.displayName = 'PostcodeSearchModal.Tip';
+export { Tip, TIP_TITLE };

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

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