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

package/dist/esm/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,23 +33,6 @@ 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 = _ref => {
   let {
@@ -58,10 +42,6 @@ const resultKey = _ref => {
   } = _ref;
   return `${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);
@@ -77,49 +57,33 @@ const useIsMobileViewport = () => {
   }, []);
   return isMobile;
 };
-const Tip = _ref2 => {
-  let {
-    compact = false,
-    className
-  } = _ref2;
-  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(_ref3 => {
-        let {
-          combination,
-          example
-        } = _ref3;
-        return _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 = _ref4 => {
+const PostcodeSearchModal = _ref2 => {
   let {
     open,
     onClose,
@@ -136,8 +100,9 @@ const PostcodeSearchModal = _ref4 => {
     loading = false,
     errorCode,
     onSelect
-  } = _ref4;
+  } = _ref2;
   const isMobile = useIsMobileViewport();
+  const rootRef = useRef(null);
   // 선택 표시는 컴포넌트가 직접 들고 있는다. 사용처는 onSelect 로 값만 받으면 된다.
   // 우편번호는 한 페이지에 중복될 수 있어 주소 전체를 키로 쓴다.
   const [selectedKey, setSelectedKey] = useState();
@@ -154,10 +119,13 @@ const PostcodeSearchModal = _ref4 => {
   }, [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);
   };
@@ -184,28 +152,42 @@ const PostcodeSearchModal = _ref4 => {
     }), _jsx(Modal.Content, {
       children: _jsxs("div", {
         className: "ncua-postcode-search-modal",
+        ref: rootRef,
         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
+          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)"
+            })]
           })]
-        }), tipVariant && _jsx(PostcodeSearchModal.Tip, {
-          compact: tipVariant === 'compact'
-        }), hasResults && _jsxs(_Fragment, {
+        }), !hasResults && _jsx(PostcodeSearchModal.Tip, {}), hasResults && _jsxs(_Fragment, {
           children: [_jsxs("p", {
             className: "ncua-postcode-search-modal__count",
             children: ["\uAC80\uC0C9 ", _jsx("b", {

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

@@ -0,0 +1,63 @@
+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 = _ref => {
+  let {
+    className
+  } = _ref;
+  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(_ref2 => {
+        let {
+          combination,
+          example
+        } = _ref2;
+        return _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/esm/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;
@@ -93,7 +97,23 @@ function baseProps() {
   };
 }
 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');
@@ -113,13 +133,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();
@@ -154,15 +174,15 @@ 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();
@@ -182,11 +202,11 @@ describe('PostcodeSearchModal — Case 5: 검색 결과 없음', () => {
       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: '존재하지않는주소',
@@ -200,14 +220,14 @@ 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({
@@ -215,7 +235,7 @@ describe('PostcodeSearchModal — Case 6: 결과 30건 이하', () => {
       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();
@@ -252,19 +272,34 @@ 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
@@ -291,7 +326,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: 대량 결과가 렌더된 상태에서
@@ -521,8 +557,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 ?? '';
@@ -534,23 +570,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();
@@ -560,4 +581,40 @@ describe('PostcodeSearchModal.Tip — 서브컴포넌트', () => {
     expect(typeof PostcodeSearchModal.Tip).toBe('function');
     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);
+  });
 });