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

package/dist/cjs/src/utils/dropdown/multiSelect.js

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.useMultiSelect = exports.useMaxSelection = exports.removeTagFromSelected = exports.isAllItemsSelected = exports.handleSelectAllItems = exports.getSelectedTags = exports.getSelectAllButtonText = void 0;
+exports.useMultiSelect = exports.useMaxSelection = void 0;
 var _react = require("react");
 var _maxSelection = require("./maxSelection");
 /**
@@ -17,7 +17,6 @@ const isAllItemsSelected = (selectedValues, options) => {
 /**
  * 전체 선택 버튼 텍스트를 반환하는 유틸 함수
  */
-exports.isAllItemsSelected = isAllItemsSelected;
 const getSelectAllButtonText = function (selectedValues, options) {
   let selectText = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : '전체 선택';
   let deselectText = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : '전체 해제';
@@ -26,7 +25,6 @@ const getSelectAllButtonText = function (selectedValues, options) {
 /**
  * 전체 선택/해제를 처리하는 유틸 함수
  */
-exports.getSelectAllButtonText = getSelectAllButtonText;
 const handleSelectAllItems = (selectedValues, options) => {
   if (isAllItemsSelected(selectedValues, options)) {
     // 전체 해제: 빈 배열 반환
@@ -38,7 +36,6 @@ const handleSelectAllItems = (selectedValues, options) => {
 /**
  * 선택된 항목들을 태그 데이터로 변환하는 유틸 함수
  */
-exports.handleSelectAllItems = handleSelectAllItems;
 const getSelectedTags = (selectedValues, options) => {
   return selectedValues.map(value => {
     const option = options.find(opt => opt.id === value);
@@ -51,7 +48,6 @@ const getSelectedTags = (selectedValues, options) => {
 /**
  * 태그 제거 시 선택값에서 해당 ID를 제거하는 유틸 함수
  */
-exports.getSelectedTags = getSelectedTags;
 const removeTagFromSelected = (selectedValues, tagIdToRemove) => {
   return selectedValues.filter(id => id !== tagIdToRemove);
 };
@@ -65,7 +61,6 @@ const removeTagFromSelected = (selectedValues, tagIdToRemove) => {
  * 도메인 규칙(`>=` 비교 등)을 외부로 노출하지 않고 헬퍼를 통해 의미만 반환한다.
  * `useMultiSelect`가 내부에서 사용하지만, 단독으로도 필요한 호출자가 쓸 수 있게 export한다.
  */
-exports.removeTagFromSelected = removeTagFromSelected;
 const useMaxSelection = (selectedValues, maxSelection) => {
   const isMaxSelectionActive = (0, _maxSelection.isMaxSelectionLimitActive)(maxSelection);
   const isMaxReached = (0, _maxSelection.isMaxSelectionReached)(selectedValues.length, maxSelection);

package/dist/cjs/src/utils/portal-position/__tests__/portalPosition.nullAnchor.test.js

@@ -0,0 +1,67 @@
+"use strict";
+
+var _vitest = require("vitest");
+var _ = require("..");
+// @vitest-environment jsdom
+
+/** afterEach 에서 호출할 구독 해제 함수 */
+const cleanups = [];
+(0, _vitest.afterEach)(() => {
+  for (const cleanup of cleanups.splice(0)) {
+    cleanup();
+  }
+  document.body.replaceChildren();
+});
+const createPanel = () => {
+  const panel = document.createElement('div');
+  document.body.appendChild(panel);
+  return panel;
+};
+/** 구독 시점에는 anchor 를 돌려주고, detach() 이후에는 null 을 돌려주는 getAnchor */
+const createDetachableAnchor = () => {
+  const element = document.createElement('button');
+  document.body.appendChild(element);
+  let current = element;
+  return {
+    getAnchor: () => current,
+    detach: () => {
+      current = null;
+    }
+  };
+};
+const track = (getAnchor, onUpdate) => {
+  const panel = createPanel();
+  cleanups.push((0, _.trackPortalPosition)({
+    getAnchor,
+    getPanel: () => panel,
+    direction: 'down',
+    onUpdate
+  }));
+};
+(0, _vitest.describe)('trackPortalPosition — 변화 시점 anchor 가 null (RSD-02)', () => {
+  (0, _vitest.it)('RSD-02 구독 뒤 anchor 가 null 이 되면 resize 에도 onUpdate 를 부르지 않는다', () => {
+    // Given: 구독 시점에는 anchor 가 있었고 이후 사라진다
+    const anchor = createDetachableAnchor();
+    const onUpdate = _vitest.vi.fn();
+    track(anchor.getAnchor, onUpdate);
+    onUpdate.mockClear();
+    anchor.detach();
+    // When: 창 크기 변화가 온다
+    window.dispatchEvent(new Event('resize'));
+    // Then: onUpdate 가 불리지 않는다
+    (0, _vitest.expect)(onUpdate).not.toHaveBeenCalled();
+  });
+  (0, _vitest.it)('RSD-02 (대조) anchor 가 남아 있으면 resize 에 onUpdate 를 부른다', () => {
+    // Given: anchor 가 계속 있다
+    const anchor = createDetachableAnchor();
+    const onUpdate = _vitest.vi.fn();
+    track(anchor.getAnchor, onUpdate);
+    onUpdate.mockClear();
+    // When: 창 크기 변화가 온다
+    window.dispatchEvent(new Event('resize'));
+    // Then: 측정한 스타일로 onUpdate 가 불린다
+    (0, _vitest.expect)(onUpdate).toHaveBeenCalledWith(_vitest.expect.objectContaining({
+      position: 'fixed'
+    }));
+  });
+});

package/dist/cjs/vitest.config.js

@@ -11,6 +11,8 @@ function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e
 // projectBaseDir 로 잡으므로, 패키지 루트 기준 상대경로(SF:src/foo.ts)로 두면 경로가
 // 해석되지 않아 커버리지가 통째로 무시된다.
 const REPO_ROOT = _nodePath.default.resolve(__dirname, '../..');
+// CI 출력은 그대로 두고 로컬에서만 리포터를 더한다 (CI 는 GitHub Actions 가 CI=true 로 설정).
+const LOCAL_REPORTERS = process.env.CI ? [] : ['text', 'html'];
 var _default = exports.default = (0, _config.defineConfig)({
   test: {
     include: ['scripts/**/__tests__/**/*.test.ts', 'src/**/__tests__/**/*.test.ts', 'assets/scripts/**/__tests__/**/*.test.ts'],
@@ -24,12 +26,27 @@ var _default = exports.default = (0, _config.defineConfig)({
       // (step-guide 의 src/index.ts 는 824줄 본체 구현이므로 그쪽에서는 제외하지 않는다.)
       '**/index.ts',
       // MCP 가 읽는 컴포넌트 메타데이터 선언 45개 — 실행 분기 없는 순수 데이터.
-      '**/*.meta.ts', 'src/types/**', 'src/constant/**'],
-      // 'text' 미포함 — 미커버 파일이 수백 개라 파일별 상세 출력이 CI 로그를 덮는다.
-      // 'lcov' 대신 'lcovonly' — 'lcov' 는 HTML 리포트까지 생성한다.
-      reporter: ['text-summary', ['lcovonly', {
+      '**/*.meta.ts', 'src/types/**', 'src/constant/**',
+      // generate:scoped-css 가 만드는 빌드 산출물(gitignore) — 존재 여부가 실행 환경마다 달라
+      // 분모가 흔들린다. git 에 없어 Sonar 스캔 대상이 아니므로 sonar 쪽 동기화는 필요 없다.
+      'src/generated/**'],
+      // CI 에는 'text' 미포함 — 미커버 파일이 수백 개라 파일별 상세 출력이 CI 로그를 덮는다.
+      // 로컬(CI 환경변수 없음)에서만 파일별 표(text)와 HTML 리포트(coverage/index.html)를 더한다.
+      // 'lcov' 대신 'lcovonly' — 'lcov' 는 HTML 리포트까지 생성한다 (CI 에서는 불필요).
+      reporter: [...LOCAL_REPORTERS, 'text-summary', ['lcovonly', {
         projectRoot: REPO_ROOT
-      }]]
+      }]],
+      // 회귀 방지 하한선 — 실측에서 약 2%p 낮춘 값 (ui-admin-mcp 와 같은 여유폭).
+      // 실측 기준: 2026-10-28, 545a9c81 — stmts 98.92 / branch 96.79 / funcs 99.19 / lines 99.65
+      // (직전 2026-10-12, 25cb4d96 — 54.91 / 44.63 / 55.20 / 55.80 에서 PR-4~9 테스트로 인상. 최종 목표 93 / 88 초과 달성)
+      // autoUpdate: false — 값은 실측을 확인하고 사람이 직접 올린다.
+      thresholds: {
+        autoUpdate: false,
+        statements: 96,
+        branches: 94,
+        functions: 97,
+        lines: 97
+      }
     }
   }
 });

package/dist/esm/assets/scripts/notification/const/icons.js

@@ -22,7 +22,6 @@ export const FULL_WIDTH_ICON_MAP = {
   success: SVG_ICONS['check-circle'],
   info: SVG_ICONS['info-circle']
 };
-export const ICON_MAP = FULL_WIDTH_ICON_MAP;
 /** message 기본 타입 아이콘. floating 과 같은 4색에 info(neutral 과 같은 핀)를 더한다. */
 export const MESSAGE_ICON_MAP = {
   neutral: SVG_ICONS['pin-02'],

package/dist/esm/assets/scripts/notification/const/index.js

@@ -1,4 +1,4 @@
 // Re-export all constants and types from separate files
 export { CLASS_NAMES } from './classNames';
-export { FLOATING_ICON_MAP, FULL_WIDTH_ICON_MAP, ICON_MAP, MESSAGE_ICON_MAP, SVG_ICONS } from './icons';
-export { CLOSE_BUTTON_SIZES, CLOSE_BUTTON_SVG_SIZES, FEATURED_ICON_SIZES, FULL_WIDTH_SIZES, getSizes, ICON_PIXEL_SIZES, MESSAGE_SIZES } from './sizes';
+export { FLOATING_ICON_MAP, FULL_WIDTH_ICON_MAP, MESSAGE_ICON_MAP, SVG_ICONS } from './icons';
+export { FULL_WIDTH_SIZES, getSizes, MESSAGE_SIZES } from './sizes';

package/dist/esm/assets/scripts/notification/const/sizes.js

@@ -1,22 +1,22 @@
 // 알림 컴포넌트 사이즈 관련 상수들
 // FeaturedIcon 사이즈
-export const FEATURED_ICON_SIZES = {
+const FEATURED_ICON_SIZES = {
   MOBILE: 'md',
   DESKTOP: 'sm'
 };
 // SVG 아이콘 픽셀 사이즈
-export const ICON_PIXEL_SIZES = {
+const ICON_PIXEL_SIZES = {
   MOBILE: '20',
   DESKTOP: '16',
   FULL_WIDTH: '16' // Full-width는 항상 고정
 };
 // 닫기 버튼 사이즈
-export const CLOSE_BUTTON_SIZES = {
+const CLOSE_BUTTON_SIZES = {
   MOBILE: 'sm',
   DESKTOP: 'xs'
 };
 // 닫기 버튼 SVG 픽셀 사이즈
-export const CLOSE_BUTTON_SVG_SIZES = {
+const CLOSE_BUTTON_SVG_SIZES = {
   xs: 16,
   sm: 20
 };

package/dist/esm/assets/scripts/notification/index.js

@@ -1,4 +1,4 @@
-export { CLASS_NAMES, FLOATING_ICON_MAP, FULL_WIDTH_ICON_MAP, ICON_MAP, SVG_ICONS } from './const';
+export { CLASS_NAMES, FLOATING_ICON_MAP, FULL_WIDTH_ICON_MAP, SVG_ICONS } from './const';
 export { FloatingNotification } from './FloatingNotification';
 export { FullWidthNotification } from './FullWidthNotification';
 export { MessageNotification } from './MessageNotification';

package/dist/esm/assets/scripts/shared/ButtonCloseX.js

@@ -1,13 +1,16 @@
 // 공통 X버튼 로직 (React ButtonCloseX 컴포넌트와 동일한 구조)
 // React ButtonCloseX와 동일한 SVG 사이즈 매핑
-export const SVG_SIZE = {
+const SVG_SIZE = {
   xs: 16,
   sm: 20,
   md: 20,
   lg: 24
 };
+// 버튼 id 난수 — 36진수 문자열에서 '0.' 뒤 9자리를 쓴다
+const BUTTON_ID_RADIX = 36;
+const BUTTON_ID_LENGTH = 9;
 // X버튼 SVG 아이콘
-export const X_CLOSE_SVG = size => `<svg width="${size}" height="${size}" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+const X_CLOSE_SVG = size => `<svg width="${size}" height="${size}" fill="none" viewBox="0 0 24 24" stroke="currentColor">
     <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12" />
   </svg>`;
 // X버튼 렌더링 유틸리티 (React ButtonCloseX와 동일한 인터페이스)
@@ -17,7 +20,7 @@ export function ButtonCloseX(size) {
   let ariaLabel = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : '닫기';
   let onClick = arguments.length > 4 ? arguments[4] : undefined;
   const svgSize = SVG_SIZE[size];
-  const buttonId = `close-btn-${Math.random().toString(36).substr(2, 9)}`;
+  const buttonId = `close-btn-${Math.random().toString(BUTTON_ID_RADIX).substr(2, BUTTON_ID_LENGTH)}`;
   const buttonHTML = `
     <button type="button" id="${buttonId}" class="ncua-button-close-x ncua-button-close-x--${size} ncua-button-close-x--${theme} ${additionalClasses}" aria-label="${ariaLabel}">
       ${X_CLOSE_SVG(svgSize.toString())}

package/dist/esm/assets/scripts/tooltip/const/classNames.js

@@ -0,0 +1,23 @@
+// Tooltip CSS 클래스명 상수들
+export const CLASS_NAMES = {
+  // 기본 클래스
+  TOOLTIP: 'ncua-tooltip',
+  TOOLTIP_ICON: 'ncua-tooltip__icon',
+  TOOLTIP_BG: 'ncua-tooltip__bg',
+  TOOLTIP_TITLE: 'ncua-tooltip__title',
+  TOOLTIP_CONTENT: 'ncua-tooltip__content',
+  TOOLTIP_CLOSE_BUTTON: 'ncua-tooltip__close-button',
+  // 수정자 클래스 (modifier classes)
+  TOOLTIP_HIDDEN_ARROW: 'ncua-tooltip--hidden-arrow',
+  TOOLTIP_STROKE: 'ncua-tooltip--stroke',
+  TOOLTIP_AUTO: 'ncua-tooltip--auto',
+  // 배경 상태 클래스
+  TOOLTIP_BG_VISIBLE: 'ncua-tooltip__bg--visible',
+  TOOLTIP_BG_MEASURING: 'ncua-tooltip__bg--measuring',
+  TOOLTIP_BG_FORCE_HIDDEN: 'ncua-tooltip__bg--force-hidden',
+  // 레이어 관련 클래스
+  TOOLTIP_GLOBAL_LAYER: 'ncua-tooltip-global-layer',
+  TOOLTIP_PANEL: 'ncua-tooltip-panel',
+  // 버튼 클래스
+  BUTTON_CLOSE_X: 'ncua-button-close-x'
+};

package/dist/esm/assets/scripts/tooltip/const/constants.js

@@ -0,0 +1,52 @@
+export const MARGIN = 10;
+export const DEFAULT_TOOLTIP_WIDTH = 200;
+export const DEFAULT_TOOLTIP_HEIGHT = 60;
+export const POSITION_PRIORITY = ['bottom', 'top', 'right', 'left'];
+// 툴팁 위치 계산 관련 상수
+export const TOOLTIP_OFFSET = 8; // 툴팁과 앵커 사이의 거리
+export const VIEWPORT_MARGIN = 8; // 뷰포트 경계와의 최소 거리
+// 아이콘 크기 상수
+export const ICON_SIZES = {
+  sm: 14,
+  md: 16
+};
+// 애니메이션 관련 상수
+export const TRANSITION_DURATION = '0.18s';
+export const OFFSCREEN_POSITION = '-99999px';
+// 툴팁 상태 관련 상수
+export const OPACITY = {
+  HIDDEN: '0',
+  VISIBLE: '1'
+};
+export const POSITION = {
+  INITIAL: '0px',
+  OFFSCREEN: OFFSCREEN_POSITION
+};
+// z-index 관련 상수
+// SCSS 토큰 `--z-index-tooltip`(base/_custom-variable.scss)과 동기 유지 — 변경 시 양쪽 같이 수정
+export const Z_INDEX = {
+  TOOLTIP_LAYER: 2000 // 툴팁 전역 레이어 기본 z-index (고도몰 기준)
+};
+// 이벤트 관련 상수
+export const EVENT_OPTIONS = {
+  PASSIVE: {
+    passive: true
+  },
+  ONCE: {
+    once: true
+  }
+};
+export const TOOLTIP_DEFAULT_VALUE = {
+  tooltipType: 'white',
+  iconType: 'stroke',
+  position: 'auto',
+  size: 'sm',
+  hideArrow: false,
+  title: '',
+  content: '',
+  type: 'short',
+  zIndex: Z_INDEX.TOOLTIP_LAYER,
+  useShadowDOM: false,
+  className: '',
+  iconColor: 'var(--gray-300)' // React Tooltip의 iconColor 기본값과 동일
+};

package/dist/esm/assets/scripts/tooltip/const/icons.js

@@ -0,0 +1,9 @@
+// SVG 아이콘들
+export const SVG_ICONS = {
+  'help-circle-stroke': size => `<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}" fill="none" viewBox="0 0 24 24" stroke="none">
+      <path stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9.09 9a3 3 0 0 1 5.83 1c0 2-3 3-3 3m.08 4h.01M22 12c0 5.523-4.477 10-10 10S2 17.523 2 12 6.477 2 12 2s10 4.477 10 10"></path>
+    </svg>`,
+  'help-circle-fill': size => `<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}" fill="none" viewBox="0 0 24 24" stroke="none">
+      <path fill="currentColor" fill-rule="evenodd" d="M12 1C5.925 1 1 5.925 1 12s4.925 11 11 11 11-4.925 11-11S18.075 1 12 1m-1.093 7.271a2 2 0 0 1 3.013 1.727V10c0 .47-.365.958-1.055 1.418a6 6 0 0 1-1.262.634 1 1 0 0 0 .633 1.897l.169-.061a8.05 8.05 0 0 0 1.57-.806c.81-.54 1.944-1.55 1.945-3.081a4 4 0 0 0-7.773-1.333 1 1 0 0 0 1.886.664 2 2 0 0 1 .874-1.06M12 16a1 1 0 1 0 0 2h.01a1 1 0 0 0 0-2z" clip-rule="evenodd"></path>
+    </svg>`
+};

package/dist/esm/assets/scripts/tooltip/const/index.js

@@ -0,0 +1,5 @@
+// Re-export all constants and types from separate files
+export { CLASS_NAMES } from './classNames';
+export { DEFAULT_TOOLTIP_HEIGHT, DEFAULT_TOOLTIP_WIDTH, EVENT_OPTIONS, ICON_SIZES, MARGIN, OFFSCREEN_POSITION, OPACITY, POSITION, POSITION_PRIORITY, TOOLTIP_DEFAULT_VALUE, TOOLTIP_OFFSET, VIEWPORT_MARGIN, Z_INDEX } from './constants';
+export { SVG_ICONS } from './icons';
+export { CSS_TEMPLATES, FALLBACK_ICON_SVG, HTML_TEMPLATES } from './templates';

package/dist/esm/assets/scripts/tooltip/const/templates.js

@@ -0,0 +1,60 @@
+import { OFFSCREEN_POSITION, TRANSITION_DURATION } from './constants';
+/**
+ * 툴팁 관련 CSS 및 HTML 템플릿
+ */
+// CSS 템플릿
+export const CSS_TEMPLATES = {
+  // 레이어 컨테이너 스타일 (클릭 통과)
+  LAYER_CONTAINER: zIndex => `
+    position: fixed;
+    inset: 0;
+    pointer-events: none;
+    z-index: ${zIndex};
+    display: block;
+  `,
+  // 툴팁 패널 스타일 (클릭 허용)
+  TOOLTIP_PANEL: zIndex => `
+    position: fixed;
+    left: ${OFFSCREEN_POSITION}; 
+    top: ${OFFSCREEN_POSITION};
+    opacity: 0;
+    transition: opacity ${TRANSITION_DURATION} ease;
+    pointer-events: auto;
+    z-index: ${zIndex};
+    right: auto;
+    bottom: auto;
+    transform: none;
+  `,
+  // 앵커 래퍼 스타일
+  ANCHOR_WRAPPER: `
+    display: inline-flex;
+    vertical-align: middle;
+    margin: 0 4px;
+  `,
+  // Shadow DOM 기본 스타일
+  // Shadow boundary는 스타일 격리하지만 CSS 커스텀 프로퍼티는 통과하므로 host 변수를 그대로 참조 가능
+  SHADOW_DOM_HOST: `
+    :host {
+      all: unset;
+      display: block;
+      font-family: var(--font-families-commerce-sans, system-ui);
+      color: black;
+    }
+  `
+};
+// HTML 템플릿
+export const HTML_TEMPLATES = {
+  // 아이콘 래퍼
+  ICON_WRAPPER: (className, iconSvg) => `<span class="${className}">${iconSvg}</span>`,
+  // 툴팁 제목
+  TOOLTIP_TITLE: (className, title) => `<span class="${className}">${title}</span>`,
+  // 툴팁 콘텐츠 (일반)
+  TOOLTIP_CONTENT: (className, content) => `<span class="${className}">${content}</span>`,
+  // 툴팁 콘텐츠 (Shadow DOM)
+  TOOLTIP_CONTENT_SHADOW: className => `<span class="${className}" data-shadow-content></span>`
+};
+// 폴백 아이콘 SVG
+export const FALLBACK_ICON_SVG = size => `<svg width="${size}" height="${size}" viewBox="0 0 16 16" aria-hidden="true">
+    <circle cx="8" cy="8" r="7" stroke="currentColor" fill="none"/>
+    <text x="8" y="11" font-size="8" text-anchor="middle" fill="currentColor">?</text>
+  </svg>`;

package/dist/esm/assets/scripts/tooltip/const/types.js

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

package/dist/esm/assets/scripts/utils/sanitize.js

@@ -16,16 +16,4 @@ import DOMPurify from 'dompurify';
  */
 export function sanitizeHtml(dirty) {
   return DOMPurify.sanitize(dirty);
-}
-/**
- * 엘리먼트에 콘텐츠를 안전하게 설정한다.
- * - string: sanitize 후 innerHTML 교체
- * - HTMLElement: 기존 자식 제거 후 appendChild
- */
-export function setSafeInnerHTML(element, content) {
-  if (content instanceof HTMLElement) {
-    element.replaceChildren(content);
-    return;
-  }
-  element.innerHTML = sanitizeHtml(content);
 }

package/dist/esm/src/__tests__/helpers/dom.js

@@ -0,0 +1,8 @@
+/** 셀렉터에 맞는 첫 요소. 없으면 셀렉터를 담아 던져 실패 위치를 바로 보여 준다. */
+export function mustQuery(root, selector) {
+  const element = root.querySelector(selector);
+  if (!element) {
+    throw new Error(`요소를 찾지 못함: ${selector}`);
+  }
+  return element;
+}

package/dist/esm/src/__tests__/helpers/fileInput.js

@@ -0,0 +1,78 @@
+// 파일 첨부 테스트 공용 헬퍼 — vanilla(assets/scripts/imageFileInput) · React(file-input · image-file-input) 가 함께 쓴다.
+// React 전용 act 감싸기는 selectFiles 의 dispatch 인자로 받아 이 모듈은 React 에 의존하지 않는다.
+import { afterEach, beforeEach, vi } from 'vitest';
+/** 내용은 검증 대상이 아니므로 최소 크기만 채운다 */
+export const DUMMY_FILE_BYTES = 4;
+/** 파일마다 type 등 속성이 달라 팩토리로 받는다 — 반환 함수는 (이름, 크기) 만 받는다 */
+export const createFileFactory = properties => function (name) {
+  let size = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : DUMMY_FILE_BYTES;
+  return new File([new Uint8Array(size)], name, properties);
+};
+/**
+ * URL.createObjectURL · revokeObjectURL 을 테스트마다 새 목으로 바꾸고 끝나면 원복한다.
+ * 모듈 최상위에서 호출해 beforeEach · afterEach 를 등록한다. 발급 URL 은 테스트마다 blob:mock/1 부터 센다.
+ */
+// 반환 타입을 적지 않으면 NPM 빌드(declaration: true)가 vi.fn 의 타입을 pnpm 내부 경로로만 이름 붙일 수 있어 TS2742 로 실패한다
+export const mockObjectUrls = () => {
+  const originalCreateObjectURL = URL.createObjectURL;
+  const originalRevokeObjectURL = URL.revokeObjectURL;
+  const createObjectURL = vi.fn();
+  const revokeObjectURL = vi.fn();
+  beforeEach(() => {
+    let issued = 0;
+    createObjectURL.mockReset().mockImplementation(() => `blob:mock/${++issued}`);
+    revokeObjectURL.mockReset();
+    URL.createObjectURL = createObjectURL;
+    URL.revokeObjectURL = revokeObjectURL;
+  });
+  afterEach(() => {
+    URL.createObjectURL = originalCreateObjectURL;
+    URL.revokeObjectURL = originalRevokeObjectURL;
+  });
+  return {
+    createObjectURL,
+    revokeObjectURL
+  };
+};
+export const fileInputOf = scope => {
+  const input = scope.querySelector('input[type="file"]');
+  if (!input) throw new Error('file input을 찾지 못했습니다');
+  return input;
+};
+export const browseButton = scope => {
+  const button = scope.querySelector('.ncua-file-input__input-container button.ncua-btn');
+  if (!button) throw new Error('찾기 버튼을 찾지 못했습니다');
+  return button;
+};
+/**
+ * jsdom 에는 파일 선택 UI 가 없어 files 를 직접 정의한 뒤 change 를 발생시킨다.
+ * React 는 상태 갱신을 반영하도록 dispatch 에 act 를 넘긴다.
+ */
+export const selectFiles = function (scope, filesToSelect) {
+  let dispatch = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : fire => fire();
+  const input = fileInputOf(scope);
+  const value = filesToSelect === null ? null : {
+    ...filesToSelect,
+    length: filesToSelect.length,
+    item: index => filesToSelect[index] ?? null,
+    [Symbol.iterator]: function* () {
+      yield* filesToSelect;
+    }
+  };
+  Object.defineProperty(input, 'files', {
+    configurable: true,
+    value
+  });
+  dispatch(() => {
+    input.dispatchEvent(new Event('change', {
+      bubbles: true
+    }));
+  });
+};
+/**
+ * actual 의 각 File 이 expected 의 몇 번째 인스턴스인지 (없으면 -1).
+ * 이 환경에서 File 은 열거 가능한 own 속성이 없어 서로 다른 File 도 toEqual 이 통과하므로 동일성으로 비교한다.
+ */
+export const indexesIn = (expected, actual) => actual.map(file => expected.indexOf(file));
+/** 목(mock) 의 마지막 호출에서 첫 인자(File[])를 꺼낸다 — 호출이 없으면 빈 배열 */
+export const lastFilesOf = mock => mock.mock.lastCall?.[0] ?? [];

package/dist/esm/src/__tests__/helpers/fixedToday.js

@@ -0,0 +1,10 @@
+import { vi } from 'vitest';
+/** 2026-10-21 (수) 정오 — 자정 경계 영향을 받지 않도록 정오로 둔다 */
+export const FIXED_TODAY = new Date('2026-10-21T12:00:00');
+/** Date 만 가짜로 고정한다 — flatpickr 내부 타이머는 실제로 흐른다. 해제는 호출 측 afterEach 의 vi.useRealTimers() */
+export const useFixedToday = () => {
+  vi.useFakeTimers({
+    toFake: ['Date']
+  });
+  vi.setSystemTime(FIXED_TODAY);
+};

package/dist/esm/src/__tests__/helpers/matchMedia.js

@@ -0,0 +1,44 @@
+const dispatchDirectly = dispatchToListeners => dispatchToListeners();
+/**
+ * jsdom 에 없는 matchMedia 를 change 리스너를 보관하는 가짜로 바꾼다.
+ * 원본 복원 함수는 `cleanups` 에 넣으므로 호출 측 afterEach 가 되돌린다.
+ */
+export function installMatchMedia(cleanups, initial) {
+  let dispatch = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : dispatchDirectly;
+  const listeners = new Set();
+  let matches = initial;
+  const hadOwn = Object.hasOwn(window, 'matchMedia');
+  const original = window.matchMedia;
+  window.matchMedia = query => ({
+    get matches() {
+      return matches;
+    },
+    media: query,
+    onchange: null,
+    addEventListener: (_type, listener) => listeners.add(listener),
+    removeEventListener: (_type, listener) => listeners.delete(listener),
+    addListener: () => undefined,
+    removeListener: () => undefined,
+    dispatchEvent: () => false
+  });
+  cleanups.push(() => {
+    if (hadOwn) {
+      window.matchMedia = original;
+    } else {
+      Reflect.deleteProperty(window, 'matchMedia');
+    }
+  });
+  return {
+    fire: next => {
+      matches = next;
+      dispatch(() => {
+        for (const listener of Array.from(listeners)) {
+          listener({
+            matches: next
+          });
+        }
+      });
+    },
+    listenerCount: () => listeners.size
+  };
+}

package/dist/esm/src/__tests__/helpers/rect.js

@@ -0,0 +1,18 @@
+/** jsdom 은 레이아웃이 없어 getBoundingClientRect 가 전부 0 이다 — 테스트가 쓸 좌표만 채운 DOMRect 를 만든다. */
+export const toRect = rect => {
+  const resolved = {
+    top: 0,
+    bottom: 0,
+    left: 0,
+    right: 0,
+    width: 0,
+    height: 0,
+    x: 0,
+    y: 0,
+    ...rect
+  };
+  return {
+    ...resolved,
+    toJSON: () => resolved
+  };
+};