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

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

@@ -0,0 +1,826 @@
+// @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 = function () {
+  let props = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  const container = document.createElement('div');
+  document.body.appendChild(container);
+  const root = createRoot(container);
+  const render = nextProps => {
+    act(() => {
+      root.render(/*#__PURE__*/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 = function (container) {
+  let relatedTarget = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : outside();
+  act(() => {
+    anchorOf(container).dispatchEvent(new MouseEvent('mouseout', {
+      bubbles: true,
+      relatedTarget
+    }));
+  });
+};
+const click = element => {
+  if (!element) throw new Error('클릭할 요소를 찾지 못했습니다');
+  act(() => {
+    element.click();
+  });
+};
+const toRect = _ref => {
+  let {
+    left,
+    top,
+    width,
+    height
+  } = _ref;
+  return {
+    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 = function (container) {
+  let anchor = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 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 좌표 · 패널 클래스 · 화살표 변수', _ref2 => {
+    let {
+      position,
+      top,
+      left,
+      arrowX
+    } = _ref2;
+    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 로 계산한다', _ref3 => {
+    let {
+      anchorTop,
+      expected
+    } = _ref3;
+    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 아이콘을 렌더한다', _ref4 => {
+    let {
+      iconStyle,
+      iconType,
+      Icon
+    } = _ref4;
+    const {
+      container
+    } = mount({
+      iconStyle,
+      iconType,
+      iconColor: 'red'
+    });
+    const expected = renderToStaticMarkup(/*#__PURE__*/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', _ref5 => {
+    let {
+      size,
+      iconSize
+    } = _ref5;
+    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: /*#__PURE__*/createElement('ul', null, /*#__PURE__*/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 툴팁 닫기 버튼에 접근 가능한 이름 "툴팁 닫기" 가 있다 (기대 동작)');
+});