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

package/dist/esm/src/components/overlays/notification/__tests__/FloatingNotification.test.js

@@ -0,0 +1,281 @@
+// @vitest-environment jsdom
+import { createElement } from 'react';
+import { createRoot } from 'react-dom/client';
+import { act } from 'react-dom/test-utils';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { NcuaNotification } from '../../../../../assets/scripts/notification/Notification';
+import { stopPositionSync } from '../../../../../assets/scripts/notification/positionSync';
+import { mustQuery } from '../../../../__tests__/helpers/dom';
+import { installMatchMedia as installFakeMatchMedia } from '../../../../__tests__/helpers/matchMedia';
+import { FloatingNotification } from '../FloatingNotification';
+// React 18에서 act() 사용 시 필요한 플래그 (미설정 시 console.error 경고 발생)
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+const HOST_SELECTOR = '.ncua-floating-notification-host';
+const SELECTOR = {
+  CARD: '.ncua-floating-notification',
+  TITLE: '.ncua-floating-notification__title',
+  SUPPORTING_TEXT: '.ncua-floating-notification__supporting-text',
+  ACTIONS: '.ncua-floating-notification__actions',
+  CLOSE: '.ncua-floating-notification__close-button',
+  FEATURED_ICON: '.ncua-featured-icon'
+};
+/** React portal 2개 + vanilla show() 1개. */
+const SHARED_HOST_CARD_COUNT = 3;
+const cleanups = [];
+const mounted = [];
+/** React 이벤트 핸들러 예외는 window error 로만 보고된다 — 클릭 경로는 이 배열이 비었는지 본다. */
+let windowErrors = [];
+function onWindowError(event) {
+  windowErrors.push(event.error);
+}
+beforeEach(() => {
+  windowErrors = [];
+  window.addEventListener('error', onWindowError);
+  cleanups.push(() => window.removeEventListener('error', onWindowError));
+});
+afterEach(() => {
+  for (const {
+    root,
+    container
+  } of mounted.splice(0)) {
+    act(() => {
+      root.unmount();
+    });
+    container.remove();
+  }
+  for (const cleanup of cleanups.splice(0).reverse()) {
+    cleanup();
+  }
+  // portal 이 시작한 위치 동기화(모듈 싱글턴)와 호스트를 걷어 다음 테스트가 새 호스트를 만들게 한다.
+  stopPositionSync();
+  for (const host of Array.from(document.querySelectorAll(HOST_SELECTOR))) {
+    host.remove();
+  }
+});
+function installMatchMedia(initial) {
+  return installFakeMatchMedia(cleanups, initial, dispatchToListeners => {
+    act(() => {
+      dispatchToListeners();
+    });
+  });
+}
+function mount(element) {
+  const container = document.createElement('div');
+  document.body.appendChild(container);
+  const root = createRoot(container);
+  act(() => {
+    root.render(element);
+  });
+  mounted.push({
+    root,
+    container
+  });
+  return container;
+}
+function render() {
+  let props = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  return mount(/*#__PURE__*/createElement(FloatingNotification, {
+    title: '제목',
+    ...props
+  }));
+}
+describe('FloatingNotification (React) — portal', () => {
+  beforeEach(() => {
+    installMatchMedia(false);
+  });
+  it('RNT-02: portal 기본(false) 이면 부모 트리 안에 인라인으로 렌더하고 호스트를 만들지 않는다', () => {
+    // Given/When: portal 없이 렌더하면
+    const container = render();
+    // Then: 카드는 컨테이너 안에 있고 호스트는 없다
+    expect(container.querySelector(SELECTOR.CARD)).not.toBeNull();
+    expect(document.querySelector(HOST_SELECTOR)).toBeNull();
+  });
+  it('RNT-02: portal 이면 effect 뒤 body 의 호스트에 포털로 렌더한다', () => {
+    // Given/When: portal 로 렌더하면
+    const container = render({
+      portal: true
+    });
+    // Then: 카드는 컨테이너가 아니라 호스트 아래에 있다
+    const host = mustQuery(document.body, HOST_SELECTOR);
+    expect(container.querySelector(SELECTOR.CARD)).toBeNull();
+    expect(mustQuery(host, SELECTOR.CARD).parentElement).toBe(host);
+  });
+  it('RNT-02: 두 인스턴스와 vanilla show() 가 같은 호스트를 공유하고, 언마운트 뒤에도 호스트는 남는다', () => {
+    // Given: portal 알림 두 개를 렌더하고
+    render({
+      portal: true,
+      title: '첫째'
+    });
+    render({
+      portal: true,
+      title: '둘째'
+    });
+    const host = mustQuery(document.body, HOST_SELECTOR);
+    // When: vanilla floating 을 show 하면
+    const vanilla = new NcuaNotification({
+      title: '바닐라',
+      type: 'floating'
+    });
+    cleanups.push(() => vanilla.destroy());
+    vanilla.show();
+    // Then: 호스트는 하나이고 세 카드가 모두 그 호스트의 자식이다
+    expect(document.querySelectorAll(HOST_SELECTOR)).toHaveLength(1);
+    expect(host.children).toHaveLength(SHARED_HOST_CARD_COUNT);
+    expect(host.querySelectorAll(`:scope > ${SELECTOR.CARD}`)).toHaveLength(SHARED_HOST_CARD_COUNT);
+    expect(vanilla.getElement().parentElement).toBe(host);
+    // When: React 쪽을 모두 언마운트하면
+    for (const {
+      root,
+      container
+    } of mounted.splice(0)) {
+      act(() => {
+        root.unmount();
+      });
+      container.remove();
+    }
+    // Then: 호스트는 문서에 남아 있다
+    expect(host.isConnected).toBe(true);
+  });
+});
+describe('FloatingNotification (React) — a11y · 닫기', () => {
+  beforeEach(() => {
+    installMatchMedia(false);
+  });
+  it.each([{
+    color: 'error',
+    role: 'alert'
+  }, {
+    color: 'warning',
+    role: 'alert'
+  }, {
+    color: 'success',
+    role: 'status'
+  }, {
+    color: 'neutral',
+    role: 'status'
+  }])('RNT-03: color $color → role="$role"', _ref => {
+    let {
+      color,
+      role
+    } = _ref;
+    // Given/When: 색상을 주어 렌더하면
+    const card = mustQuery(render({
+      color
+    }), SELECTOR.CARD);
+    // Then: 색상에 맞는 live region role 이다
+    expect(card.getAttribute('role')).toBe(role);
+  });
+  it('RNT-03: aria-labelledby 는 제목 id, aria-describedby 는 supportingText 가 있을 때만 그 id 를 가리킨다', () => {
+    // Given/When: 본문 유무만 다르게 두 개 렌더하면
+    const withText = mustQuery(render({
+      supportingText: '본문'
+    }), SELECTOR.CARD);
+    const withoutText = mustQuery(render(), SELECTOR.CARD);
+    // Then: 제목 · 본문 id 와 연결되고, 본문이 없으면 describedby 가 없다
+    expect(withText.getAttribute('aria-labelledby')).toBe(mustQuery(withText, SELECTOR.TITLE).id);
+    expect(withText.getAttribute('aria-describedby')).toBe(mustQuery(withText, SELECTOR.SUPPORTING_TEXT).id);
+    expect(withoutText.hasAttribute('aria-describedby')).toBe(false);
+  });
+  it('RNT-10: 닫기 버튼은 클릭하면 onClose 를 부르지만 접근 가능한 이름(aria-label)이 없다', () => {
+    // 현재 동작 고정 — 결함 후보 #597 CA-02 · RTP-18 (공용 ButtonCloseX 가 aria-label 을 받지 않음)
+    // Given: onClose 가 있는 알림을 렌더하고
+    const onClose = vi.fn();
+    const button = mustQuery(render({
+      onClose
+    }), SELECTOR.CLOSE);
+    // When: 닫기 버튼을 클릭하면
+    act(() => {
+      button.click();
+    });
+    // Then: onClose 는 불리고 예외는 없지만 버튼 이름이 비어 있다
+    expect(onClose).toHaveBeenCalled();
+    expect(windowErrors).toEqual([]);
+    expect(button.getAttribute('aria-label')).toBeNull();
+  });
+  it.todo('RNT-10 floating 닫기 버튼에 "알림 닫기" 접근 가능한 이름이 있다 (vanilla 와 같게)');
+});
+describe('FloatingNotification (React) — 모바일', () => {
+  it.each([{
+    viewport: 'mobile',
+    matches: true,
+    featuredIcon: 'md',
+    closeButton: 'sm'
+  }, {
+    viewport: 'desktop',
+    matches: false,
+    featuredIcon: 'sm',
+    closeButton: 'xs'
+  }])('RNT-04: $viewport 에서 마운트하면 FeaturedIcon $featuredIcon · 닫기 $closeButton 크기다', _ref2 => {
+    let {
+      matches,
+      featuredIcon,
+      closeButton
+    } = _ref2;
+    // Given/When: 매체 조건을 맞추고 닫기 버튼이 있는 알림을 렌더하면
+    installMatchMedia(matches);
+    const container = render({
+      onClose: vi.fn()
+    });
+    // Then: 첫 effect 뒤 그 화면 크기다
+    const icon = mustQuery(container, SELECTOR.FEATURED_ICON);
+    const close = mustQuery(container, SELECTOR.CLOSE);
+    expect(icon.classList.contains(`ncua-featured-icon--${featuredIcon}`)).toBe(true);
+    expect(close.classList.contains(`ncua-button-close-x--${closeButton}`)).toBe(true);
+  });
+  it('RNT-04 · RNT-09: 데스크톱에서 모바일로 바뀌면 onClose 를 부르지만 카드는 그대로 남는다', () => {
+    // 현재 동작 고정 — 결함 후보 #620 (전환 시 onClose 만 부르고 카드를 남김 — vanilla 는 제거)
+    // Given: 데스크톱에서 렌더된 알림이
+    const media = installMatchMedia(false);
+    const onClose = vi.fn();
+    const container = render({
+      onClose
+    });
+    // When: 모바일로 전환되면
+    media.fire(true);
+    // Then: onClose 는 불리고 크기는 모바일이 되지만 카드는 소비자가 지울 때까지 남는다
+    const card = mustQuery(container, SELECTOR.CARD);
+    expect(onClose).toHaveBeenCalled();
+    expect(mustQuery(card, SELECTOR.FEATURED_ICON).classList.contains('ncua-featured-icon--md')).toBe(true);
+    expect(card.isConnected).toBe(true);
+  });
+  it('RNT-09: 처음부터 모바일이면 마운트 시 onClose 를 부르지 않는다', () => {
+    // 현재 동작 고정 — 결함 후보 #620 (vanilla 는 생성 시 즉시 onClose — React 는 전환 때만)
+    // Given/When: 모바일 매체 조건에서 렌더하면
+    installMatchMedia(true);
+    const onClose = vi.fn();
+    const container = render({
+      onClose
+    });
+    // Then: 카드는 표시되고 onClose 는 불리지 않는다
+    expect(container.querySelector(SELECTOR.CARD)).not.toBeNull();
+    expect(onClose).not.toHaveBeenCalled();
+  });
+  it.todo('RNT-09 모바일 진입 시 React · vanilla 가 같은 규칙으로 onClose 와 카드 제거를 처리한다');
+});
+describe('FloatingNotification (React) — 결함 후보: info · 빈 actions', () => {
+  beforeEach(() => {
+    installMatchMedia(false);
+  });
+  it('RNT-08: color info 면 --info 클래스로 아이콘 없이 렌더한다 (vanilla 는 neutral 클래스 + 핀 아이콘)', () => {
+    // 현재 동작 고정 — 결함 후보 #620 (info 가 iconMap 에 없어 아이콘 미렌더 — vanilla 는 neutral 로 대체)
+    // Given/When: info 로 렌더하면
+    const card = mustQuery(render({
+      color: 'info'
+    }), SELECTOR.CARD);
+    // Then: --info 클래스이고 FeaturedIcon 이 없다
+    expect(card.classList.contains('ncua-floating-notification--info')).toBe(true);
+    expect(card.classList.contains('ncua-floating-notification--neutral')).toBe(false);
+    expect(card.querySelector(SELECTOR.FEATURED_ICON)).toBeNull();
+  });
+  it.todo('RNT-08 floating color info 는 vanilla 와 같게 neutral 클래스와 핀 아이콘으로 렌더한다');
+  it('RNT-11: actions 가 빈 배열이면 버튼 없는 빈 __actions 래퍼를 렌더한다', () => {
+    // 현재 동작 고정 — 결함 후보 #620 (`actions &&` 판정이라 빈 배열도 래퍼를 만듦)
+    // Given/When: actions 를 빈 배열로 렌더하면
+    const wrapper = mustQuery(render({
+      actions: []
+    }), SELECTOR.ACTIONS);
+    // Then: 래퍼는 있지만 버튼이 없다
+    expect(wrapper.querySelector('button')).toBeNull();
+  });
+  it.todo('RNT-11 actions 가 빈 배열이면 __actions 래퍼를 렌더하지 않는다');
+});

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

@@ -282,4 +282,16 @@ describe('MessageNotification (React) — 액션 버튼 색상(hierarchy)', () =
     // Then: 핸들러가 1회 호출된다
     expect(onClick).toHaveBeenCalledTimes(1);
   });
+});
+describe('MessageNotification (React) — 아이콘 폴백', () => {
+  it('RNT-12: 타입 밖 color 로 기본 아이콘 매핑이 비면 핀 아이콘으로 폴백한다', () => {
+    // Given/When: 기본 매개변수가 대체하지 못하는 타입 밖 color 로 렌더하면 (JS 소비자 오입력 재현)
+    const container = renderMessageNotification({
+      color: 'unknown'
+    });
+    // Then: 아이콘 자리가 비지 않고 Pin02 로 렌더된다
+    const pin = iconPathD(Pin02);
+    expect(pin).not.toBeNull();
+    expect(renderedIconPathD(container)).toBe(pin);
+  });
 });

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

@@ -60,4 +60,4 @@ const Tip = _ref => {
   });
 };
 Tip.displayName = 'PostcodeSearchModal.Tip';
-export { Tip, TIP_TITLE };
+export { Tip };

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

@@ -0,0 +1,139 @@
+// @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 = function () {
+  let overrides = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  return {
+    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(/*#__PURE__*/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(/*#__PURE__*/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(/*#__PURE__*/createElement(PostcodeSearchModal, baseProps({
+      searchQuery: SEARCH_QUERY,
+      onSearchQueryChange
+    })));
+    // When: 지우기 버튼을 클릭한다
+    act(() => mustQuery(body, '.ncua-input__clear').click());
+    // Then: 빈 문자열로 알린다
+    expect(onSearchQueryChange).toHaveBeenCalledWith('');
+  });
+});