@ncds/ui-admin 1.8.28-alpha.0 → 1.8.28-alpha.1

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

@@ -0,0 +1,112 @@
+// @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 { PostcodeSearchModal } from '../PostcodeSearchModal';
+// React 18에서 act() 사용 시 필요한 플래그 (미설정 시 console.error 경고 발생)
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+/**
+ * Modal.Content 를 스크롤 컨테이너 클래스가 없는 div 로 바꿀 수 있게 한다.
+ * 실제 사용처는 항상 Modal.Content 안이라 "스크롤 컨테이너를 못 찾는" 분기에는 이 대역으로만 닿는다.
+ * plain 이 false 면 실구현을 그대로 쓴다.
+ */
+const contentMode = vi.hoisted(() => ({ plain: false }));
+vi.mock('../../modal', async (importOriginal) => {
+    const actual = await importOriginal();
+    const react = await import('react');
+    const Content = (props) => contentMode.plain
+        ? react.createElement('div', { className: 'plain-content' }, props.children)
+        : react.createElement(actual.Modal.Content, props);
+    const Modal = Object.assign((props) => react.createElement(actual.Modal, props), actual.Modal, {
+        Content,
+    });
+    return { ...actual, Modal };
+});
+const RESULT_COUNT = 3;
+const ZIP_CODE_BASE = 10000;
+/** 본문을 아래로 내린 상태를 흉내 낼 scrollTop 값 */
+const SCROLLED_OFFSET = 120;
+const SEARCH_QUERY = '판교로';
+const makeResults = (count) => Array.from({ length: count }, (_, i) => ({
+    zipCode: String(ZIP_CODE_BASE + i),
+    roadAddress: `도로명 주소 ${i}`,
+    jibunAddress: `지번 주소 ${i}`,
+}));
+const baseProps = (overrides = {}) => ({
+    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 mounted = [];
+afterEach(() => {
+    for (const { root, container } of mounted.splice(0)) {
+        act(() => root.unmount());
+        container.remove();
+    }
+    contentMode.plain = false;
+    vi.unstubAllGlobals();
+});
+/** Modal 은 document.body 포털이라 조회 기준은 body 다 */
+const mount = (node) => {
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    const root = createRoot(container);
+    mounted.push({ root, container });
+    act(() => root.render(node));
+    return document.body;
+};
+const mustQuery = (root, selector) => {
+    const found = root.querySelector(selector);
+    if (!found)
+        throw new Error(`요소를 찾을 수 없습니다: ${selector}`);
+    return found;
+};
+/** jsdom 은 레이아웃이 없어 scrollTop 이 항상 0 이므로, 값을 덮어쓰고 scroll 이벤트를 쏜다 */
+const scroll = (scroller) => {
+    Object.defineProperty(scroller, 'scrollTop', { value: SCROLLED_OFFSET, configurable: true });
+    act(() => {
+        scroller.dispatchEvent(new Event('scroll'));
+    });
+};
+const isFixed = (body) => mustQuery(body, '.ncua-postcode-search-modal__search-area').classList.contains('is-fixed');
+describe('PostcodeSearchModal — 뷰포트 판정 · 스크롤 컨테이너 · 검색어 지우기 (RSD-03)', () => {
+    it('RSD-03 matchMedia 가 없는 환경에서도 렌더하고 PC 판정(pc 페이지네이션)을 유지한다', () => {
+        // Given: matchMedia 를 제거한 환경 (SSR · 구형 브라우저)
+        vi.stubGlobal('matchMedia', undefined);
+        expect(typeof window.matchMedia).toBe('undefined');
+        // When: 결과가 있는 모달을 렌더한다
+        const body = mount(createElement(PostcodeSearchModal, baseProps({ results: makeResults(RESULT_COUNT), totalCount: RESULT_COUNT })));
+        // Then: 결과 목록이 있고 페이지네이션은 pc 다
+        expect(body.querySelectorAll('.ncua-postcode-search-modal__item').length).toBe(RESULT_COUNT);
+        expect(mustQuery(body, '.ncua-pagination').classList.contains('ncua-pagination--pc')).toBe(true);
+    });
+    it('RSD-03 스크롤 컨테이너(.ncua-modal__content) 밖에 렌더되면 경계선 감시를 걸지 않아 스크롤해도 is-fixed 가 없다', () => {
+        // Given: 스크롤 컨테이너 클래스가 없는 본문 대역 안에 결과와 함께 렌더
+        contentMode.plain = true;
+        const body = mount(createElement(PostcodeSearchModal, baseProps({ results: makeResults(RESULT_COUNT), totalCount: RESULT_COUNT })));
+        // When: 대역 본문을 스크롤한다
+        scroll(mustQuery(body, '.plain-content'));
+        // Then: is-fixed 가 붙지 않는다 (실제 Modal.Content 안에서 붙는 대조는 PostcodeSearchModal.test.ts
+        // '결과를 스크롤하면 is-fixed 가 붙고, 맨 위로 돌아오면 다시 사라진다')
+        expect(body.querySelector('.ncua-modal__content')).toBeNull();
+        expect(isFixed(body)).toBe(false);
+    });
+    it('RSD-03 검색어 지우기 버튼을 클릭하면 onSearchQueryChange 를 빈 문자열로 부른다', () => {
+        // Given: 검색어가 있는 모달
+        const onSearchQueryChange = vi.fn();
+        const body = mount(createElement(PostcodeSearchModal, baseProps({ searchQuery: SEARCH_QUERY, onSearchQueryChange })));
+        // When: 지우기 버튼을 클릭한다
+        act(() => mustQuery(body, '.ncua-input__clear').click());
+        // Then: 빈 문자열로 알린다
+        expect(onSearchQueryChange).toHaveBeenCalledWith('');
+    });
+});

package/dist/temp/src/components/overlays/tooltip/__tests__/Tooltip.test.d.ts

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

package/dist/temp/src/components/overlays/tooltip/__tests__/Tooltip.test.js

@@ -0,0 +1,538 @@
+// @vitest-environment jsdom
+//
+// React Tooltip — 위험 목록표 RTP-xx (PR-7e).
+// 화살표 오프셋 순수 함수는 utils.test.ts 가 덮는다. 하위 구현(ButtonCloseX · 아이콘 · calculateArrowOffsetX)은 실구현을 쓴다.
+// 보안 모델: React Tooltip 은 title · content 를 ReactNode 로 렌더해 HTML 문자열 삽입 경로가 없다 —
+// vanilla Tooltip(sanitizeHtml 후 innerHTML)과 달리 sanitize 단언 대상이 아니다.
+import { AlertCircle, AlertCircleFill, HelpCircle, HelpCircleFill } from '@ncds/ui-admin-icon';
+import { createElement } from 'react';
+import { createRoot } from 'react-dom/client';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { act } from 'react-dom/test-utils';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { TOOLTIP_OFFSET as VANILLA_TOOLTIP_OFFSET } from '../../../../../assets/scripts/tooltip/const';
+import { Tooltip } from '../Tooltip';
+import { ARROW_EDGE_MARGIN } from '../utils';
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+/** 앵커 · 패널 크기 — 좌표 기대값은 이 값으로 계산한다 */
+const ANCHOR_LEFT = 400;
+const ANCHOR_TOP = 300;
+const ANCHOR_SIZE = 16;
+const PANEL_WIDTH = 200;
+const PANEL_HEIGHT = 60;
+/** 소스 Tooltip.tsx 의 위치 상수 (export 되지 않아 값을 옮겨 적는다) */
+const TOOLTIP_OFFSET_REACT = 6;
+const EDGE_ALIGN_OFFSET = 12;
+const VIEWPORT_MARGIN = 8;
+const ICON_SIZE_SM = 14;
+const ICON_SIZE_MD = 16;
+const half = (value) => value / 2;
+const mounted = [];
+const cleanups = [];
+/** rAF 콜백은 보관만 한다 — 실제 rAF(약 16ms)가 act 밖에서 상태를 바꾸지 않도록 */
+const pendingFrames = new Map();
+let nextFrameId = 0;
+beforeEach(() => {
+    vi.spyOn(window, 'requestAnimationFrame').mockImplementation((callback) => {
+        nextFrameId += 1;
+        pendingFrames.set(nextFrameId, callback);
+        return nextFrameId;
+    });
+    vi.spyOn(window, 'cancelAnimationFrame').mockImplementation((id) => {
+        pendingFrames.delete(id);
+    });
+});
+afterEach(() => {
+    for (const { root, container } of mounted.splice(0)) {
+        act(() => {
+            root.unmount();
+        });
+        container.remove();
+    }
+    for (const cleanup of cleanups.splice(0))
+        cleanup();
+    pendingFrames.clear();
+    vi.restoreAllMocks();
+});
+/* ========== 공통 헬퍼 ========== */
+const mount = (props = {}) => {
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    const root = createRoot(container);
+    const render = (nextProps) => {
+        act(() => {
+            root.render(createElement(Tooltip, nextProps));
+        });
+    };
+    render(props);
+    const entry = { root, container };
+    mounted.push(entry);
+    const unmount = () => {
+        act(() => {
+            root.unmount();
+        });
+        mounted.splice(mounted.indexOf(entry), 1);
+        container.remove();
+    };
+    return { container, rerender: render, unmount };
+};
+/** React 가 relatedTarget 으로 enter/leave 를 합성하므로, 포인터가 오가는 바깥 요소를 둔다 */
+const outside = () => {
+    const element = document.createElement('div');
+    document.body.appendChild(element);
+    cleanups.push(() => element.remove());
+    return element;
+};
+const anchorOf = (container) => {
+    const anchor = container.querySelector('.ncua-tooltip');
+    if (!anchor)
+        throw new Error('툴팁 앵커를 찾지 못했습니다');
+    return anchor;
+};
+/** 포털 패널 — 한 테스트에 툴팁 하나만 마운트한다 */
+const portalPanel = () => {
+    const panel = document.querySelector('.ncua-tooltip-panel');
+    if (!panel)
+        throw new Error('툴팁 패널을 찾지 못했습니다');
+    return panel;
+};
+const hover = (container) => {
+    act(() => {
+        anchorOf(container).dispatchEvent(new MouseEvent('mouseover', { bubbles: true, relatedTarget: outside() }));
+    });
+};
+const leave = (container, relatedTarget = outside()) => {
+    act(() => {
+        anchorOf(container).dispatchEvent(new MouseEvent('mouseout', { bubbles: true, relatedTarget }));
+    });
+};
+const click = (element) => {
+    if (!element)
+        throw new Error('클릭할 요소를 찾지 못했습니다');
+    act(() => {
+        element.click();
+    });
+};
+const toRect = ({ left, top, width, height }) => ({
+    left,
+    top,
+    width,
+    height,
+    right: left + width,
+    bottom: top + height,
+    x: left,
+    y: top,
+    toJSON: () => ({}),
+});
+const stubRect = (element, box) => {
+    element.getBoundingClientRect = () => toRect(box);
+};
+const ANCHOR_BOX = { left: ANCHOR_LEFT, top: ANCHOR_TOP, width: ANCHOR_SIZE, height: ANCHOR_SIZE };
+const PANEL_BOX = { left: 0, top: 0, width: PANEL_WIDTH, height: PANEL_HEIGHT };
+const stubLayout = (container, anchor = ANCHOR_BOX) => {
+    stubRect(anchorOf(container), anchor);
+    stubRect(portalPanel(), PANEL_BOX);
+};
+const isVisible = (panel) => panel.classList.contains('ncua-tooltip__bg--visible');
+const px = (value) => `${value}px`;
+const coordsOf = (panel) => ({ top: panel.style.top, left: panel.style.left });
+/* ========== P0 ========== */
+describe('RTP-01 short hover 표시 · 숨김', () => {
+    it('RTP-01 진입 시 패널을 보이고 좌표를 잡는다', () => {
+        const { container } = mount({ position: 'bottom', title: '타이틀' });
+        stubLayout(container);
+        hover(container);
+        const panel = portalPanel();
+        expect(isVisible(panel)).toBe(true);
+        expect(panel.style.opacity).toBe('1');
+        expect(coordsOf(panel)).toEqual({
+            top: px(ANCHOR_TOP + ANCHOR_SIZE + TOOLTIP_OFFSET_REACT),
+            left: px(ANCHOR_LEFT + half(ANCHOR_SIZE) - half(PANEL_WIDTH)),
+        });
+    });
+    it('RTP-01 바깥으로 이탈하면 숨긴다', () => {
+        const { container } = mount({ position: 'bottom', title: '타이틀' });
+        stubLayout(container);
+        hover(container);
+        leave(container);
+        const panel = portalPanel();
+        expect(isVisible(panel)).toBe(false);
+        expect(panel.style.opacity).toBe('0');
+    });
+    it('RTP-01 아이콘에서 포털 패널로 옮기면 이탈이 아니어서 유지한다', () => {
+        const { container } = mount({ position: 'bottom', title: '타이틀' });
+        stubLayout(container);
+        hover(container);
+        leave(container, portalPanel());
+        expect(isVisible(portalPanel())).toBe(true);
+    });
+});
+describe('RTP-02 long 닫기', () => {
+    const closeButton = () => portalPanel().querySelector('.ncua-tooltip__close-button');
+    it('RTP-02 이탈해도 유지한다', () => {
+        const { container } = mount({ type: 'long', position: 'bottom', title: '타이틀' });
+        stubLayout(container);
+        hover(container);
+        leave(container);
+        expect(isVisible(portalPanel())).toBe(true);
+    });
+    it('RTP-02 X 클릭 → 숨김 + force-hidden, 이탈 없이 재진입하면 무시, 이탈 후 재진입하면 표시', () => {
+        const { container } = mount({ type: 'long', position: 'bottom', title: '타이틀' });
+        stubLayout(container);
+        hover(container);
+        click(closeButton());
+        const afterClose = {
+            visible: isVisible(portalPanel()),
+            forceHidden: portalPanel().classList.contains('ncua-tooltip__bg--force-hidden'),
+        };
+        hover(container);
+        const visibleOnReenterWithoutLeave = isVisible(portalPanel());
+        leave(container);
+        hover(container);
+        expect(afterClose).toEqual({ visible: false, forceHidden: true });
+        expect(visibleOnReenterWithoutLeave).toBe(false);
+        expect(isVisible(portalPanel())).toBe(true);
+        expect(portalPanel().classList.contains('ncua-tooltip__bg--force-hidden')).toBe(false);
+    });
+});
+describe('RTP-03 forceVisible 외부 제어', () => {
+    it('RTP-03 true 면 마운트 시 표시하고 이탈해도 유지한다', () => {
+        const { container } = mount({ forceVisible: true, position: 'bottom', title: '타이틀' });
+        const visibleOnMount = isVisible(portalPanel());
+        leave(container);
+        expect(visibleOnMount).toBe(true);
+        expect(isVisible(portalPanel())).toBe(true);
+        expect(portalPanel().style.opacity).toBe('1');
+    });
+    it('RTP-03 false 면 진입해도 표시하지 않는다', () => {
+        const { container } = mount({ forceVisible: false, position: 'bottom', title: '타이틀' });
+        stubLayout(container);
+        hover(container);
+        expect(isVisible(portalPanel())).toBe(false);
+        expect(portalPanel().style.opacity).toBe('0');
+    });
+});
+/* ========== 나머지 분기 ========== */
+const hasPanelClass = (panel, modifier) => panel.classList.contains(`ncua-tooltip__bg--${modifier}`);
+const arrowXOf = (panel) => panel.style.getPropertyValue('--ncua-tooltip-arrow-x');
+/** 앵커를 옮긴 뒤 재계산 여부를 보기 위한 이동량 */
+const MOVE_DELTA = 50;
+/** 위 공간이 모자라 auto 가 bottom 을 고르는 앵커 top */
+const ANCHOR_TOP_CRAMPED = 20;
+describe('RTP-04 위치 계산', () => {
+    const CENTER_LEFT = ANCHOR_LEFT + half(ANCHOR_SIZE) - half(PANEL_WIDTH);
+    const MIDDLE_TOP = ANCHOR_TOP + half(ANCHOR_SIZE) - half(PANEL_HEIGHT);
+    const ABOVE_TOP = ANCHOR_TOP - PANEL_HEIGHT - TOOLTIP_OFFSET_REACT;
+    const BELOW_TOP = ANCHOR_TOP + ANCHOR_SIZE + TOOLTIP_OFFSET_REACT;
+    const EDGE_LEFT = ANCHOR_LEFT - EDGE_ALIGN_OFFSET;
+    const EDGE_RIGHT = ANCHOR_LEFT + ANCHOR_SIZE - PANEL_WIDTH + EDGE_ALIGN_OFFSET;
+    const CENTER_ARROW = px(half(PANEL_WIDTH));
+    it.each([
+        { position: 'top', top: ABOVE_TOP, left: CENTER_LEFT, arrowX: CENTER_ARROW },
+        { position: 'bottom', top: BELOW_TOP, left: CENTER_LEFT, arrowX: CENTER_ARROW },
+        { position: 'left', top: MIDDLE_TOP, left: ANCHOR_LEFT - PANEL_WIDTH - TOOLTIP_OFFSET_REACT, arrowX: '' },
+        { position: 'right', top: MIDDLE_TOP, left: ANCHOR_LEFT + ANCHOR_SIZE + TOOLTIP_OFFSET_REACT, arrowX: '' },
+        { position: 'top-left', top: ABOVE_TOP, left: EDGE_LEFT, arrowX: '' },
+        { position: 'top-right', top: ABOVE_TOP, left: EDGE_RIGHT, arrowX: '' },
+        { position: 'bottom-left', top: BELOW_TOP, left: EDGE_LEFT, arrowX: '' },
+        { position: 'bottom-right', top: BELOW_TOP, left: EDGE_RIGHT, arrowX: '' },
+    ])('RTP-04 $position 좌표 · 패널 클래스 · 화살표 변수', ({ position, top, left, arrowX }) => {
+        const { container } = mount({ position, title: '타이틀' });
+        stubLayout(container);
+        hover(container);
+        const panel = portalPanel();
+        expect(coordsOf(panel)).toEqual({ top: px(top), left: px(left) });
+        expect(hasPanelClass(panel, position)).toBe(true);
+        expect(arrowXOf(panel)).toBe(arrowX);
+    });
+    it('RTP-04 auto 는 표시 전 bottom 클래스로 시작한다', () => {
+        mount({ title: '타이틀' });
+        expect(hasPanelClass(portalPanel(), 'bottom')).toBe(true);
+    });
+    it.each([
+        { anchorTop: ANCHOR_TOP, expected: 'top' },
+        { anchorTop: ANCHOR_TOP_CRAMPED, expected: 'bottom' },
+    ])('RTP-04 auto 는 앵커 top $anchorTop 이면 $expected 로 계산한다', ({ anchorTop, expected }) => {
+        const { container } = mount({ title: '타이틀' });
+        stubLayout(container, { ...ANCHOR_BOX, top: anchorTop });
+        hover(container);
+        expect(hasPanelClass(portalPanel(), expected)).toBe(true);
+        expect(anchorOf(container).classList.contains('ncua-tooltip--auto')).toBe(true);
+    });
+    it('RTP-04 왼쪽 · 위 경계를 넘으면 여백까지 밀고, 화살표는 패널 모서리 여백까지만 이동한다', () => {
+        const { container } = mount({ position: 'top', title: '타이틀' });
+        stubLayout(container, { ...ANCHOR_BOX, left: 0, top: 0 });
+        hover(container);
+        expect(coordsOf(portalPanel())).toEqual({ top: px(VIEWPORT_MARGIN), left: px(VIEWPORT_MARGIN) });
+        expect(arrowXOf(portalPanel())).toBe(px(ARROW_EDGE_MARGIN));
+    });
+    it('RTP-04 오른쪽 · 아래 경계를 넘으면 뷰포트 안쪽 여백까지 당긴다', () => {
+        const { container } = mount({ position: 'bottom', title: '타이틀' });
+        stubLayout(container, {
+            ...ANCHOR_BOX,
+            left: window.innerWidth - ANCHOR_SIZE,
+            top: window.innerHeight - ANCHOR_SIZE,
+        });
+        hover(container);
+        expect(coordsOf(portalPanel())).toEqual({
+            top: px(window.innerHeight - PANEL_HEIGHT - VIEWPORT_MARGIN),
+            left: px(window.innerWidth - PANEL_WIDTH - VIEWPORT_MARGIN),
+        });
+    });
+});
+describe('RTP-05 resize · scroll 재계산', () => {
+    const movedCoords = () => ({
+        top: px(ANCHOR_TOP + ANCHOR_SIZE + TOOLTIP_OFFSET_REACT),
+        left: px(ANCHOR_LEFT + MOVE_DELTA + half(ANCHOR_SIZE) - half(PANEL_WIDTH)),
+    });
+    it.each(['resize', 'scroll'])('RTP-05 표시 중 %s 이면 좌표를 다시 계산한다', (eventName) => {
+        const { container } = mount({ position: 'bottom', title: '타이틀' });
+        stubLayout(container);
+        hover(container);
+        stubRect(anchorOf(container), { ...ANCHOR_BOX, left: ANCHOR_LEFT + MOVE_DELTA });
+        act(() => {
+            window.dispatchEvent(new Event(eventName));
+        });
+        expect(coordsOf(portalPanel())).toEqual(movedCoords());
+    });
+    it('RTP-05 숨기면 리스너를 해제해 이후 resize 에 반응하지 않는다', () => {
+        const { container } = mount({ position: 'bottom', title: '타이틀' });
+        stubLayout(container);
+        hover(container);
+        const shown = coordsOf(portalPanel());
+        leave(container);
+        stubRect(anchorOf(container), { ...ANCHOR_BOX, left: ANCHOR_LEFT + MOVE_DELTA });
+        act(() => {
+            window.dispatchEvent(new Event('resize'));
+        });
+        expect(coordsOf(portalPanel())).toEqual(shown);
+    });
+});
+describe('RTP-06 hover rAF 재계산', () => {
+    const runFrames = () => {
+        act(() => {
+            for (const [id, callback] of Array.from(pendingFrames)) {
+                pendingFrames.delete(id);
+                callback(0);
+            }
+        });
+    };
+    it('RTP-06 진입 직후 계산하고, 다음 프레임에 한 번 더 계산한다', () => {
+        const { container } = mount({ position: 'bottom', title: '타이틀' });
+        stubLayout(container);
+        hover(container);
+        const leftOnEnter = portalPanel().style.left;
+        stubRect(anchorOf(container), { ...ANCHOR_BOX, left: ANCHOR_LEFT + MOVE_DELTA });
+        runFrames();
+        const centeredLeft = (anchorLeft) => px(anchorLeft + half(ANCHOR_SIZE) - half(PANEL_WIDTH));
+        expect([leftOnEnter, portalPanel().style.left]).toEqual([
+            centeredLeft(ANCHOR_LEFT),
+            centeredLeft(ANCHOR_LEFT + MOVE_DELTA),
+        ]);
+    });
+    it('RTP-06 연속 진입이면 대기 중인 프레임을 취소하고 새로 등록한다', () => {
+        const { container } = mount({ position: 'bottom', title: '타이틀' });
+        stubLayout(container);
+        hover(container);
+        const firstFrame = nextFrameId;
+        hover(container);
+        expect(window.cancelAnimationFrame).toHaveBeenCalledWith(firstFrame);
+        expect(Array.from(pendingFrames.keys())).toEqual([nextFrameId]);
+    });
+    it('RTP-06 프레임 대기 중 unmount 하면 그 프레임을 취소한다', () => {
+        const { container, unmount } = mount({ position: 'bottom', title: '타이틀' });
+        stubLayout(container);
+        hover(container);
+        const pendingFrame = nextFrameId;
+        unmount();
+        expect(window.cancelAnimationFrame).toHaveBeenCalledWith(pendingFrame);
+    });
+});
+describe('RTP-07 disablePortal', () => {
+    it('RTP-07 패널을 앵커 안에 인라인으로 두고 opacity 만 스타일로 준다, hover 해도 위치 계산이 없다', () => {
+        const { container } = mount({ disablePortal: true, title: '타이틀' });
+        const panel = anchorOf(container).querySelector('.ncua-tooltip__bg');
+        if (!panel)
+            throw new Error('인라인 패널을 찾지 못했습니다');
+        // disablePortal 이면 style 에 top · left 가 아예 없어 좌표로는 계산 여부를 가릴 수 없다 — 앵커 측정 호출을 본다
+        const measureAnchor = vi.fn(() => toRect(ANCHOR_BOX));
+        anchorOf(container).getBoundingClientRect = measureAnchor;
+        hover(container);
+        expect(document.querySelector('.ncua-tooltip-panel')).toBeNull();
+        expect(isVisible(panel)).toBe(true);
+        expect([panel.style.opacity, panel.style.top, panel.style.left]).toEqual(['1', '', '']);
+        expect(measureAnchor).not.toHaveBeenCalled();
+    });
+});
+describe('RTP-08 포털 대상', () => {
+    it('RTP-08 #tooltip-global-layer 가 있으면 그 안에 패널을 둔다', () => {
+        const layer = document.createElement('div');
+        layer.id = 'tooltip-global-layer';
+        document.body.appendChild(layer);
+        cleanups.push(() => layer.remove());
+        mount({ title: '타이틀' });
+        expect(portalPanel().parentElement).toBe(layer);
+    });
+    it('RTP-08 전역 레이어가 없으면 body 에 둔다', () => {
+        mount({ title: '타이틀' });
+        expect(portalPanel().parentElement).toBe(document.body);
+    });
+});
+describe('RTP-09 아이콘', () => {
+    it.each([
+        { iconStyle: 'help-circle', iconType: 'stroke', Icon: HelpCircle },
+        { iconStyle: 'help-circle', iconType: 'fill', Icon: HelpCircleFill },
+        { iconStyle: 'alert-circle', iconType: 'stroke', Icon: AlertCircle },
+        { iconStyle: 'alert-circle', iconType: 'fill', Icon: AlertCircleFill },
+    ])('RTP-09 $iconStyle · $iconType 아이콘을 렌더한다', ({ iconStyle, iconType, Icon }) => {
+        const { container } = mount({ iconStyle, iconType, iconColor: 'red' });
+        const expected = renderToStaticMarkup(createElement(Icon, { width: ICON_SIZE_SM, height: ICON_SIZE_SM, color: 'red' }));
+        expect(anchorOf(container).querySelector('svg')?.outerHTML).toBe(expected);
+    });
+    it.each([
+        { size: 'sm', iconSize: ICON_SIZE_SM },
+        { size: 'md', iconSize: ICON_SIZE_MD },
+    ])('RTP-09 size $size 면 아이콘 크기 $iconSize', ({ size, iconSize }) => {
+        const { container } = mount({ size });
+        expect(anchorOf(container).querySelector('svg')?.getAttribute('width')).toBe(String(iconSize));
+    });
+});
+describe('RTP-10 클래스 · zIndex', () => {
+    it('RTP-10 앵커에 size · type · hideArrow · stroke · auto · className modifier 를 붙인다', () => {
+        const { container } = mount({ size: 'md', type: 'long', hideArrow: true, className: 'custom-anchor' });
+        const anchor = anchorOf(container);
+        expect(Array.from(anchor.classList)).toEqual(expect.arrayContaining([
+            'ncua-tooltip--md',
+            'ncua-tooltip--long',
+            'ncua-tooltip--hidden-arrow',
+            'ncua-tooltip--stroke',
+            'ncua-tooltip--auto',
+            'custom-anchor',
+        ]));
+    });
+    it('RTP-10 fill · 고정 position 이면 stroke · auto modifier 가 없다', () => {
+        const { container } = mount({ iconType: 'fill', position: 'top' });
+        const anchor = anchorOf(container);
+        expect(anchor.classList).not.toContain('ncua-tooltip--stroke');
+        expect(anchor.classList).not.toContain('ncua-tooltip--auto');
+    });
+    it('RTP-10 패널에 tooltipType · panelClassName 을 붙이고 zIndex 가 있으면 style 로 준다', () => {
+        const zIndex = 3000;
+        mount({ tooltipType: 'black', panelClassName: 'custom-panel', zIndex });
+        const panel = portalPanel();
+        expect(Array.from(panel.classList)).toEqual(expect.arrayContaining(['ncua-tooltip__bg--black', 'custom-panel']));
+        expect(panel.style.zIndex).toBe(String(zIndex));
+    });
+    it('RTP-10 zIndex 가 없으면 style 에 z-index 가 없다', () => {
+        mount({});
+        expect(portalPanel().style.zIndex).toBe('');
+    });
+});
+describe('RTP-11 title · content', () => {
+    it('RTP-11 title 과 ReactNode content 를 렌더한다', () => {
+        mount({ title: '타이틀', content: createElement('ul', null, createElement('li', null, '항목')) });
+        const panel = portalPanel();
+        expect(panel.querySelector('.ncua-tooltip__title')?.textContent).toBe('타이틀');
+        expect(panel.querySelector('.ncua-tooltip__content li')?.textContent).toBe('항목');
+    });
+    it('RTP-11 title · content 가 없으면 그 요소가 없다', () => {
+        mount({});
+        const panel = portalPanel();
+        expect([panel.querySelector('.ncua-tooltip__title'), panel.querySelector('.ncua-tooltip__content')]).toEqual([
+            null,
+            null,
+        ]);
+    });
+    it('RTP-11 long 이면 닫기 버튼을 tooltipType 반대 테마로 둔다', () => {
+        mount({ type: 'long', tooltipType: 'black' });
+        const button = portalPanel().querySelector('.ncua-tooltip__close-button');
+        expect(button?.classList.contains('ncua-button-close-x--light')).toBe(true);
+    });
+});
+/* ========== 결함 후보 · 계약 불일치 ========== */
+describe('RTP-12 forceVisible + long 닫기', () => {
+    it('RTP-12 forceVisible 이면 X 를 눌러도 패널이 그대로이고, 풀어도 이탈 전까지 hover 를 무시한다', () => {
+        // 현재 동작 고정 — 결함 후보: 후속 이슈 (effectiveVisible = forceVisible 이라 X 무반응 · 닫힘 콜백 없음, 남은 isManuallyClose 가 hover 를 막음)
+        const { container, rerender } = mount({ type: 'long', forceVisible: true, position: 'bottom', title: '타이틀' });
+        stubLayout(container);
+        click(portalPanel().querySelector('.ncua-tooltip__close-button'));
+        const afterClose = { visible: isVisible(portalPanel()), opacity: portalPanel().style.opacity };
+        rerender({ type: 'long', position: 'bottom', title: '타이틀' });
+        hover(container);
+        expect(afterClose).toEqual({ visible: true, opacity: '1' });
+        expect(isVisible(portalPanel())).toBe(false);
+    });
+    it.todo('RTP-12 forceVisible + long 에서 X 를 누르면 닫힘을 알리는 콜백을 호출하고, forceVisible 을 풀면 hover 가 바로 동작한다');
+});
+describe('RTP-13 0 값 처리', () => {
+    it('RTP-13 zIndex={0} 은 무시되고 content={0} 은 텍스트 "0" 으로 렌더된다', () => {
+        // 현재 동작 고정 — 결함 후보: 후속 이슈 (zIndex && … · content && … 의 falsy 판정)
+        mount({ zIndex: 0, content: 0 });
+        const panel = portalPanel();
+        expect(panel.style.zIndex).toBe('');
+        expect(panel.querySelector('.ncua-tooltip__content')).toBeNull();
+        expect(panel.textContent).toBe('0');
+    });
+    it.todo('RTP-13 zIndex={0} 은 style 에 반영하고, content={0} 은 콘텐츠 요소 안에 렌더한다');
+});
+describe('RTP-14 포커스 표시', () => {
+    it('RTP-14 앵커에 tabindex · role · aria-describedby 가 없고 focusin 으로 표시되지 않는다', () => {
+        // 현재 동작 고정 — 결함 후보: 후속 이슈 (계약 불일치 — 문서 "마우스를 올리거나 포커스할 때 나타납니다", TT-23 과 한 행)
+        const { container } = mount({ title: '타이틀' });
+        const anchor = anchorOf(container);
+        act(() => {
+            anchor.dispatchEvent(new FocusEvent('focusin', { bubbles: true }));
+        });
+        expect([
+            anchor.getAttribute('tabindex'),
+            anchor.getAttribute('role'),
+            anchor.getAttribute('aria-describedby'),
+        ]).toEqual([null, null, null]);
+        expect(isVisible(portalPanel())).toBe(false);
+    });
+    it.todo('RTP-14 앵커가 포커스를 받을 수 있고, 포커스하면 패널을 표시하며 aria-describedby 로 연결한다');
+});
+describe('RTP-15 문서 기본값 표기', () => {
+    it('RTP-15 코드 기본값은 size sm · tooltipType white 다 (Props 표와 일치, 예제 제목과 불일치)', () => {
+        // 현재 동작 고정 — 결함 후보: 후속 이슈 (계약 불일치 — 문서 예제 제목 "Medium Size (기본)" · "black (기본)" 이 Props 표 · 코드와 모순)
+        const { container } = mount({});
+        expect(anchorOf(container).classList.contains('ncua-tooltip--sm')).toBe(true);
+        expect(hasPanelClass(portalPanel(), 'white')).toBe(true);
+    });
+    it.todo('RTP-15 문서 예제 제목의 기본값 표기를 Props 표(size sm · tooltipType white)와 맞춘다');
+});
+describe('RTP-16 위치 상수', () => {
+    it('RTP-16 React 앵커-패널 간격은 6px 로 vanilla(8px)와 다르다', () => {
+        // 현재 동작 고정 — 결함 후보: 후속 이슈 (주석 "HTML 구현체와 동일한 상수" 인데 TOOLTIP_OFFSET 6 vs 8)
+        const { container } = mount({ position: 'bottom', title: '타이틀' });
+        stubLayout(container);
+        hover(container);
+        const gap = Number.parseFloat(portalPanel().style.top) - (ANCHOR_TOP + ANCHOR_SIZE);
+        expect(gap).toBe(TOOLTIP_OFFSET_REACT);
+        expect(gap).not.toBe(VANILLA_TOOLTIP_OFFSET);
+    });
+    it.todo('RTP-16 React 와 vanilla 의 앵커-패널 간격 상수를 같은 값으로 맞춘다');
+});
+describe('RTP-17 타입 밖 position', () => {
+    it('RTP-17 어떤 방향에도 안 걸리는 값은 (0,0) → 경계 보정 (8,8), 클래스는 그 값이다 (캐스팅 구동, 결함 아님)', () => {
+        const position = 'diagonal';
+        const { container } = mount({ position, title: '타이틀' });
+        stubLayout(container);
+        hover(container);
+        expect(coordsOf(portalPanel())).toEqual({ top: px(VIEWPORT_MARGIN), left: px(VIEWPORT_MARGIN) });
+        expect(hasPanelClass(portalPanel(), 'diagonal')).toBe(true);
+    });
+});
+describe('RTP-18 long 닫기 버튼 이름', () => {
+    it('RTP-18 long 툴팁 닫기 버튼에는 aria-label 이 없다 (Tooltip 이 넘긴 값이 버려짐)', () => {
+        // 현재 동작 고정 — 결함 후보: 후속 이슈 (RTP-18 — ButtonCloseX 가 aria-label 을 받지 않아 Tooltip 이 넘긴 "툴팁 닫기" 가 버려짐, #597 CA-02 와 같은 유형)
+        const { container } = mount({ type: 'long', position: 'bottom', title: '타이틀' });
+        stubLayout(container);
+        hover(container);
+        const button = portalPanel().querySelector('.ncua-tooltip__close-button');
+        if (!button)
+            throw new Error('닫기 버튼을 찾지 못했습니다');
+        expect(button.getAttribute('aria-label')).toBeNull();
+    });
+    it.todo('RTP-18 long 툴팁 닫기 버튼에 접근 가능한 이름 "툴팁 닫기" 가 있다 (기대 동작)');
+});

package/dist/temp/src/components/tab/__tests__/TabButton.test.d.ts

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