@ncds/ui-admin 1.8.21-alpha.8 → 1.8.21

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

@@ -1,21 +1,23 @@
 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 { 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;
-/** 이 건수를 넘으면 Tip 을 압축 버전으로 전환한다 (기획서 기준) */
-const TIP_COMPACT_THRESHOLD = 30;
+/** 검색 조합 안내 문구를 띄우는 기준 — 결과가 이 수를 넘을 때만 노출한다 */
+const SEARCH_HINT_MIN_TOTAL_COUNT = 30;
 /** 반응형 전환 기준 — 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 = '검색';
@@ -23,7 +25,6 @@ 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 통합). */
@@ -32,25 +33,8 @@ 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);
@@ -67,12 +51,34 @@ const useIsMobileViewport = () => {
     }, []);
     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))) }))] }));
+/**
+ * 본문이 위로 스크롤됐는지 여부.
+ * 고정된 검색 영역과 스크롤되는 결과 사이의 경계선을 스크롤 중에만 그리기 위해 쓴다.
+ * 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;
 };
-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();
+    const rootRef = useRef(null);
     // 선택 표시는 컴포넌트가 직접 들고 있는다. 사용처는 onSelect 로 값만 받으면 된다.
     // 우편번호는 한 페이지에 중복될 수 있어 주소 전체를 키로 쓴다.
     const [selectedKey, setSelectedKey] = useState();
@@ -90,10 +96,13 @@ const PostcodeSearchModal = ({ open, onClose, zIndex, className, searchQuery, on
     }, [open]);
     const hasError = Boolean(errorCode);
     const hasResults = !hasError && results.length > 0;
+    // 결과가 적으면 굳이 검색 조합을 안내하지 않는다.
+    const showSearchHint = hasResults && totalCount > SEARCH_HINT_MIN_TOTAL_COUNT;
     // 검색을 실행한 검색어와 현재 입력값이 같을 때만 "결과 없음"으로 본다.
     // 입력 중에는 두 값이 달라지고, 응답을 기다리는 동안에는 loading 이 막는다.
     const showEmptyState = !hasError && !loading && results.length === 0 && searchQuery !== '' && searchQuery === searchedQuery;
-    const tipVariant = resolveTipVariant(hasResults, totalCount);
+    // 결과 목록이 있을 때만 스크롤이 생기므로 그때만 감시한다.
+    const isContentScrolled = useIsContentScrolled(rootRef, open && hasResults);
     const handleSearchQueryChange = (event) => {
         onSearchQueryChange(event.target.value);
     };
@@ -108,7 +117,9 @@ const PostcodeSearchModal = ({ open, onClose, zIndex, className, searchQuery, on
         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: () => {
+    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: () => {
                                                 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/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", { 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';
+export { Tip, TIP_TITLE };

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

@@ -7,11 +7,11 @@ import { PostcodeSearchModal } from '../PostcodeSearchModal';
 // React 18에서 act() 사용 시 필요한 플래그 (미설정 시 console.error 경고 발생)
 globalThis.IS_REACT_ACT_ENVIRONMENT = true;
 const PAGE_SIZE = 15;
-/** Tip 압축 임계값(30) 이하 결과 건수 — Tip 미노출 케이스 */
+/** 한 페이지에 다 들어가는 결과 건수 — Tip 카드 미노출 케이스 */
 const SMALL_RESULT_COUNT = 5;
 /** SMALL_RESULT_COUNT 기준 총 페이지 수 */
 const SMALL_RESULT_TOTAL_PAGE = 1;
-/** Tip 압축 임계값(30) 초과 결과 건수 — Tip 압축 + totalPage(3) <= 페이지 그룹 크기(10) */
+/** 여러 페이지로 나뉘는 결과 건수 — totalPage(3) <= 페이지 그룹 크기(10) */
 const LARGE_RESULT_COUNT = 45;
 /** LARGE_RESULT_COUNT 기준 총 페이지 수 */
 const LARGE_RESULT_TOTAL_PAGE = 3;
@@ -19,6 +19,10 @@ const LARGE_RESULT_TOTAL_PAGE = 3;
 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;
@@ -89,7 +93,21 @@ function baseProps(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 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 });
+    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');
@@ -109,13 +127,13 @@ afterEach(() => {
     vi.unstubAllGlobals();
 });
 describe('PostcodeSearchModal — Case 1: 검색 전 초기 상태', () => {
-    it('상세 Tip 만 노출되고 카운트·리스트·페이지네이션·EmptyState 는 렌더되지 않는다', () => {
+    it('Tip 카드만 노출되고 카운트·리스트·페이지네이션·EmptyState 는 렌더되지 않는다', () => {
         // Given: 검색어·결과가 비어 있고 에러도 없는 상태에서
         // When: 모달을 열면
         const el = render(baseProps());
-        // Then: 상세 Tip 만 노출되고 결과 영역은 전부 미노출이다
+        // Then: Tip 카드만 노출되고 결과 영역은 전부 미노출이다
         expect(tipOf(el)).not.toBeNull();
-        expect(isCompactTip(el)).toBe(false);
+        expect(resultTitleOf(el)).toBeNull();
         expect(countLabelOf(el)).toBeNull();
         expect(el.querySelector('.ncua-postcode-search-modal__list')).toBeNull();
         expect(paginationOf(el)).toBeNull();
@@ -153,12 +171,12 @@ describe('PostcodeSearchModal — Case 2~4: 에러코드별 hint 매핑', () =>
         expect(inputRootOf(el)?.classList.contains('destructive')).toBe(true);
         expect(hintOf(el)?.textContent).toBe(hint);
     });
-    it('에러 상태에서는 상세 Tip 이 노출되고 리스트·EmptyState 는 미노출이다', () => {
+    it('에러 상태에서는 Tip 카드가 노출되고 리스트·EmptyState 는 미노출이다', () => {
         // Given/When: 에러코드를 전달해 렌더하면
         const el = render(baseProps({ searchQuery: '서', errorCode: 'E0008' }));
-        // Then: 상세 Tip 만 남는다
+        // Then: Tip 카드만 남는다
         expect(tipOf(el)).not.toBeNull();
-        expect(isCompactTip(el)).toBe(false);
+        expect(resultTitleOf(el)).toBeNull();
         expect(el.querySelector('.ncua-postcode-search-modal__list')).toBeNull();
         expect(emptyStateOf(el)).toBeNull();
         expect(paginationOf(el)).toBeNull();
@@ -170,11 +188,11 @@ describe('PostcodeSearchModal — Case 5: 검색 결과 없음', () => {
         render(baseProps({ searchQuery: '', results: [], totalCount: 0 }));
         // When: 검색을 실행하지 않고 글자만 입력하면
         const el = render(baseProps({ searchQuery: '존재하지않는주소', results: [], totalCount: 0 }));
-        // Then: "검색 결과가 없습니다." 는 뜨지 않고 상세 Tip 만 유지된다
+        // Then: "검색 결과가 없습니다." 는 뜨지 않고 Tip 카드만 유지된다
         expect(emptyStateOf(el)).toBeNull();
         expect(tipOf(el)).not.toBeNull();
     });
-    it('EmptyState 가 "검색 결과가 없습니다." 로 렌더되고 상세 Tip 이 유지된다', () => {
+    it('EmptyState 가 "검색 결과가 없습니다." 로 렌더되고 Tip 카드가 유지된다', () => {
         // Given: 검색어는 있으나 결과가 0건인 상태에서
         const el = render(baseProps({ searchQuery: '존재하지않는주소', results: [], totalCount: 0 }));
         // When: 검색 버튼을 눌러 실제로 검색을 실행하면
@@ -184,18 +202,18 @@ describe('PostcodeSearchModal — Case 5: 검색 결과 없음', () => {
         // Then: EmptyState 가 노출되고 오류 스타일은 아니며 페이지네이션은 없다
         expect(emptyStateOf(el)?.textContent).toContain('검색 결과가 없습니다.');
         expect(tipOf(el)).not.toBeNull();
-        expect(isCompactTip(el)).toBe(false);
+        expect(resultTitleOf(el)).toBeNull();
         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 은 미노출된다', () => {
+describe('PostcodeSearchModal — Case 6: 결과 있음', () => {
+    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 은 사라진다
+        // Then: 카운트·리스트가 노출되고 Tip 카드는 사라진다
         expect(countLabelOf(el)?.textContent).toBe(`검색 ${SMALL_RESULT_COUNT}개`);
         expect(itemsOf(el)).toHaveLength(SMALL_RESULT_COUNT);
         expect(tipOf(el)).toBeNull();
@@ -224,15 +242,26 @@ describe('PostcodeSearchModal — Case 6: 결과 30건 이하', () => {
         expect(el.querySelectorAll('.ncua-pagination__page-num')).toHaveLength(SMALL_RESULT_TOTAL_PAGE);
     });
 });
-describe('PostcodeSearchModal — Case 7: 결과 30건 초과', () => {
-    it('카운트 "검색 45개" 와 15행 리스트, 압축 Tip 이 렌더된다', () => {
+describe('PostcodeSearchModal — Case 7: 결과 여러 페이지', () => {
+    it('카운트 "검색 45개" 와 15행 리스트가 렌더되고 Tip 카드 대신 결과 안내 문구가 남는다', () => {
         // Given/When: 45건 중 첫 페이지 15건을 전달하면
         const el = render(baseProps({ searchQuery: '판교로', results: makeResults(PAGE_SIZE), totalCount: LARGE_RESULT_COUNT }));
-        // Then: 압축 Tip 이 노출된다
+        // 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);
+        expect(tipOf(el)).toBeNull();
+        expect(resultTitleOf(el)?.textContent).toBe('아래 조합으로 검색 시 주소를 더 쉽게 찾을 수 있어요.');
+        expect(resultDescOf(el)?.textContent).toBe('도로명+건물번호, 지역명+지번, 지역명+건물명(아파트명)');
+    });
+    it('검색 인풋과 안내 문구가 같은 고정 영역 안에 묶이고 결과 목록은 그 밖에 있다', () => {
+        // Given/When: 결과가 여러 페이지인 상태로 렌더하면
+        const el = render(baseProps({ searchQuery: '판교로', results: makeResults(PAGE_SIZE), totalCount: LARGE_RESULT_COUNT }));
+        // Then: 상단 고정 영역이 인풋 행과 안내 문구를 함께 감싸고, 스크롤되는 목록은 밖에 남는다
+        const searchArea = searchAreaOf(el);
+        expect(searchArea?.querySelector('.ncua-postcode-search-modal__search')).not.toBeNull();
+        expect(searchArea?.querySelector('.ncua-postcode-search-modal__result-title')).not.toBeNull();
+        expect(searchArea?.querySelector('.ncua-postcode-search-modal__result-desc')).not.toBeNull();
+        expect(searchArea?.querySelector('.ncua-postcode-search-modal__list')).toBeNull();
     });
     it('totalPage(3) 가 PAGER_WINDOW(10) 이하이므로 점프 버튼은 노출되지 않는다', () => {
         // Given/When: totalCount=45, PAGE_SIZE=15 → totalPage=3
@@ -251,7 +280,8 @@ describe('PostcodeSearchModal — Case 8: 결과 대량', () => {
         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);
+        expect(tipOf(el)).toBeNull();
+        expect(resultTitleOf(el)).not.toBeNull();
     });
     it('3페이지 버튼을 클릭하면 onPageChange(3) 이 호출된다', () => {
         // Given: 대량 결과가 렌더된 상태에서
@@ -418,8 +448,8 @@ describe('PostcodeSearchModal — 반응형 전환', () => {
     });
 });
 describe('PostcodeSearchModal.Tip — 서브컴포넌트', () => {
-    it('상세 모드는 조합 3종과 예시 주소를 모두 보여준다', () => {
-        // Given/When: 상세 Tip 이 노출되는 초기 상태로 렌더하면
+    it('조합 3종과 예시 주소를 모두 보여준다', () => {
+        // Given/When: Tip 카드가 노출되는 초기 상태로 렌더하면
         const el = render(baseProps());
         // Then: 안내 문구와 3개 조합, 예시 주소가 모두 포함된다
         const tipText = tipOf(el)?.textContent ?? '';
@@ -431,19 +461,8 @@ describe('PostcodeSearchModal.Tip — 서브컴포넌트', () => {
         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 을 렌더하면
+        // Given/When: Tip 카드를 렌더하면
         const el = render(baseProps());
         // Then: 지정한 아이콘 클래스를 가진 svg 가 존재한다
         expect(tipOf(el)?.querySelector('svg.ncua-postcode-search-modal__tip-icon')).not.toBeNull();
@@ -454,3 +473,31 @@ describe('PostcodeSearchModal.Tip — 서브컴포넌트', () => {
         expect(PostcodeSearchModal.Tip.displayName).toBe('PostcodeSearchModal.Tip');
     });
 });
+describe('PostcodeSearchModal — 검색 영역 고정 표시', () => {
+    it('결과가 있어도 스크롤하기 전에는 is-fixed 가 붙지 않는다', () => {
+        // Given/When: 결과를 스크롤하지 않은 상태로 렌더하면
+        const el = render(baseProps({ searchQuery: '판교로', results: makeResults(PAGE_SIZE), totalCount: LARGE_RESULT_COUNT }));
+        // Then: 검색 영역이 아직 떠 있지 않으므로 경계선 클래스도 없다
+        expect(isFixedSearchArea(el)).toBe(false);
+    });
+    it('결과를 스크롤하면 is-fixed 가 붙고, 맨 위로 돌아오면 다시 사라진다', () => {
+        // Given: 결과가 렌더된 상태에서
+        const el = render(baseProps({ searchQuery: '판교로', results: makeResults(PAGE_SIZE), totalCount: LARGE_RESULT_COUNT }));
+        // When: 본문을 아래로 스크롤하면
+        scrollContent(el, SCROLLED_OFFSET);
+        // Then: 경계선 클래스가 붙는다
+        expect(isFixedSearchArea(el)).toBe(true);
+        // When: 다시 맨 위로 올리면
+        scrollContent(el, SCROLL_TOP);
+        // Then: 경계선 클래스가 사라진다
+        expect(isFixedSearchArea(el)).toBe(false);
+    });
+    it('결과가 없으면 스크롤이 일어나도 is-fixed 가 붙지 않는다', () => {
+        // Given: 초기 상태(결과 없음)로 렌더하고
+        const el = render(baseProps());
+        // When: 본문 스크롤 이벤트가 들어와도
+        scrollContent(el, SCROLLED_OFFSET);
+        // Then: 고정할 대상이 없으므로 클래스는 붙지 않는다
+        expect(isFixedSearchArea(el)).toBe(false);
+    });
+});