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

package/dist/temp/assets/scripts/tooltip/const/icons.d.ts

@@ -0,0 +1,4 @@
+export declare const SVG_ICONS: {
+    readonly 'help-circle-stroke': (size: number) => string;
+    readonly 'help-circle-fill': (size: number) => string;
+};

package/dist/temp/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/temp/assets/scripts/tooltip/const/index.d.ts

@@ -0,0 +1,5 @@
+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';
+export type { CalculatedPosition, TooltipOptions } from './types';

package/dist/temp/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/temp/assets/scripts/tooltip/const/templates.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 툴팁 관련 CSS 및 HTML 템플릿
+ */
+export declare const CSS_TEMPLATES: {
+    readonly LAYER_CONTAINER: (zIndex: number) => string;
+    readonly TOOLTIP_PANEL: (zIndex: number) => string;
+    readonly ANCHOR_WRAPPER: "\n    display: inline-flex;\n    vertical-align: middle;\n    margin: 0 4px;\n  ";
+    readonly SHADOW_DOM_HOST: "\n    :host {\n      all: unset;\n      display: block;\n      font-family: var(--font-families-commerce-sans, system-ui);\n      color: black;\n    }\n  ";
+};
+export declare const HTML_TEMPLATES: {
+    readonly ICON_WRAPPER: (className: string, iconSvg: string) => string;
+    readonly TOOLTIP_TITLE: (className: string, title: string) => string;
+    readonly TOOLTIP_CONTENT: (className: string, content: string) => string;
+    readonly TOOLTIP_CONTENT_SHADOW: (className: string) => string;
+};
+export declare const FALLBACK_ICON_SVG: (size: number) => string;

package/dist/temp/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/temp/assets/scripts/tooltip/const/types.d.ts

@@ -0,0 +1,17 @@
+export interface TooltipOptions {
+    tooltipType?: 'white' | 'black';
+    iconType?: 'stroke' | 'fill';
+    position?: 'top' | 'bottom' | 'left' | 'right' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'auto';
+    size?: 'sm' | 'md';
+    hideArrow?: boolean;
+    title?: string;
+    content?: string;
+    type?: 'long' | 'short';
+    zIndex?: number;
+    useShadowDOM?: boolean;
+    className?: string;
+    panelClassName?: string;
+    forceVisible?: boolean;
+    iconColor?: string;
+}
+export type CalculatedPosition = 'top' | 'bottom' | 'left' | 'right' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';

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

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

package/dist/temp/assets/scripts/utils/sanitize.d.ts

@@ -14,9 +14,3 @@
  * 이벤트 바인딩은 addEventListener로 별도 처리할 것.
  */
 export declare function sanitizeHtml(dirty: string): string;
-/**
- * 엘리먼트에 콘텐츠를 안전하게 설정한다.
- * - string: sanitize 후 innerHTML 교체
- * - HTMLElement: 기존 자식 제거 후 appendChild
- */
-export declare function setSafeInnerHTML(element: HTMLElement, content: string | HTMLElement): void;

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

@@ -17,15 +17,3 @@ 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/temp/src/__tests__/helpers/dom.d.ts

@@ -0,0 +1,2 @@
+/** 셀렉터에 맞는 첫 요소. 없으면 셀렉터를 담아 던져 실패 위치를 바로 보여 준다. */
+export declare function mustQuery<T extends Element>(root: ParentNode, selector: string): T;

package/dist/temp/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/temp/src/__tests__/helpers/fileInput.d.ts

@@ -0,0 +1,27 @@
+import { type Mock, vi } from 'vitest';
+/** 내용은 검증 대상이 아니므로 최소 크기만 채운다 */
+export declare const DUMMY_FILE_BYTES = 4;
+/** 파일마다 type 등 속성이 달라 팩토리로 받는다 — 반환 함수는 (이름, 크기) 만 받는다 */
+export declare const createFileFactory: (properties: FilePropertyBag) => (name: string, size?: number) => File;
+/**
+ * URL.createObjectURL · revokeObjectURL 을 테스트마다 새 목으로 바꾸고 끝나면 원복한다.
+ * 모듈 최상위에서 호출해 beforeEach · afterEach 를 등록한다. 발급 URL 은 테스트마다 blob:mock/1 부터 센다.
+ */
+export declare const mockObjectUrls: () => {
+    createObjectURL: Mock<(object: Blob | MediaSource) => string>;
+    revokeObjectURL: Mock<(url: string) => void>;
+};
+export declare const fileInputOf: (scope: HTMLElement) => HTMLInputElement;
+export declare const browseButton: (scope: HTMLElement) => HTMLButtonElement;
+/**
+ * jsdom 에는 파일 선택 UI 가 없어 files 를 직접 정의한 뒤 change 를 발생시킨다.
+ * React 는 상태 갱신을 반영하도록 dispatch 에 act 를 넘긴다.
+ */
+export declare const selectFiles: (scope: HTMLElement, filesToSelect: File[] | null, dispatch?: (fire: () => void) => void) => void;
+/**
+ * actual 의 각 File 이 expected 의 몇 번째 인스턴스인지 (없으면 -1).
+ * 이 환경에서 File 은 열거 가능한 own 속성이 없어 서로 다른 File 도 toEqual 이 통과하므로 동일성으로 비교한다.
+ */
+export declare const indexesIn: (expected: File[], actual: File[]) => number[];
+/** 목(mock) 의 마지막 호출에서 첫 인자(File[])를 꺼낸다 — 호출이 없으면 빈 배열 */
+export declare const lastFilesOf: (mock: ReturnType<typeof vi.fn>) => File[];

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

@@ -0,0 +1,70 @@
+// 파일 첨부 테스트 공용 헬퍼 — 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) => (name, size = DUMMY_FILE_BYTES) => 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 = (scope, filesToSelect, dispatch = (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/temp/src/__tests__/helpers/fixedToday.d.ts

@@ -0,0 +1,4 @@
+/** 2026-10-21 (수) 정오 — 자정 경계 영향을 받지 않도록 정오로 둔다 */
+export declare const FIXED_TODAY: Date;
+/** Date 만 가짜로 고정한다 — flatpickr 내부 타이머는 실제로 흐른다. 해제는 호출 측 afterEach 의 vi.useRealTimers() */
+export declare const useFixedToday: () => void;

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

@@ -0,0 +1,8 @@
+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/temp/src/__tests__/helpers/matchMedia.d.ts

@@ -0,0 +1,13 @@
+/** React 쪽은 리스너 발화를 act 로 감싸야 해서 발화 방식을 주입받는다. */
+type Dispatch = (dispatchToListeners: () => void) => void;
+export interface FakeMediaQuery {
+    /** 저장된 change 리스너에 matches 값을 담아 발화한다. */
+    fire: (matches: boolean) => void;
+    listenerCount: () => number;
+}
+/**
+ * jsdom 에 없는 matchMedia 를 change 리스너를 보관하는 가짜로 바꾼다.
+ * 원본 복원 함수는 `cleanups` 에 넣으므로 호출 측 afterEach 가 되돌린다.
+ */
+export declare function installMatchMedia(cleanups: (() => void)[], initial: boolean, dispatch?: Dispatch): FakeMediaQuery;
+export {};

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

@@ -0,0 +1,42 @@
+const dispatchDirectly = (dispatchToListeners) => dispatchToListeners();
+/**
+ * jsdom 에 없는 matchMedia 를 change 리스너를 보관하는 가짜로 바꾼다.
+ * 원본 복원 함수는 `cleanups` 에 넣으므로 호출 측 afterEach 가 되돌린다.
+ */
+export function installMatchMedia(cleanups, initial, dispatch = 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/temp/src/__tests__/helpers/rect.d.ts

@@ -0,0 +1,2 @@
+/** jsdom 은 레이아웃이 없어 getBoundingClientRect 가 전부 0 이다 — 테스트가 쓸 좌표만 채운 DOMRect 를 만든다. */
+export declare const toRect: (rect: Partial<DOMRect>) => DOMRect;

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

@@ -0,0 +1,5 @@
+/** 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 };
+};

package/dist/temp/src/components/action/button/__tests__/Button.test.d.ts

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

package/dist/temp/src/components/action/button/__tests__/Button.test.js

@@ -0,0 +1,180 @@
+// @vitest-environment jsdom
+import { createElement, createRef } from 'react';
+import { createRoot } from 'react-dom/client';
+import { act } from 'react-dom/test-utils';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { COLOR } from '../../../../../constant/color';
+import { Button } from '../Button';
+// React 18에서 act() 사용 시 필요한 플래그 (미설정 시 console.error 경고 발생)
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+const LABEL = '저장';
+/** afterEach 에서 unmount 할 루트 */
+const mounted = [];
+afterEach(() => {
+    for (const { root, container } of mounted.splice(0)) {
+        act(() => root.unmount());
+        container.remove();
+    }
+});
+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 { container };
+};
+const button = (props = {}) => createElement(Button, { label: LABEL, ...props });
+/** 폼 안에 렌더하고 submit 발생을 기록한다 (preventDefault 로 jsdom 의 폼 전송을 막는다) */
+const mountInForm = (node) => {
+    const submits = [];
+    const view = mount(createElement('form', {
+        onSubmit: (event) => {
+            event.preventDefault();
+            submits.push(event.nativeEvent);
+        },
+    }, node));
+    return { ...view, submits };
+};
+const mustQuery = (root, selector) => {
+    const found = root.querySelector(selector);
+    if (!found)
+        throw new Error(`요소를 찾을 수 없습니다: ${selector}`);
+    return found;
+};
+describe('Button — type 기본값 (BTN-04)', () => {
+    it('BTN-04 type 을 넘기지 않은 Button 은 폼 안에서 클릭하면 폼을 제출한다', () => {
+        // 현재 동작 고정 — 결함 후보: #620 BTN-04 추가 기록 (VNT-12 같은 뿌리 — 공용 Button 에 type 기본값이 없어 의도 없는 폼 제출)
+        // Given: type 없이 폼 안에 렌더
+        const view = mountInForm(button());
+        const element = mustQuery(view.container, 'button');
+        // When: 클릭한다
+        act(() => element.click());
+        // Then: type 속성이 없어 브라우저 기본값 submit 으로 동작해 폼이 제출된다
+        expect(element.getAttribute('type')).toBeNull();
+        expect(element.type).toBe('submit');
+        expect(view.submits).toHaveLength(1);
+    });
+    it('BTN-04 (대조) type="button" 을 넘기면 폼 안에서 클릭해도 제출하지 않는다', () => {
+        // Given: type="button" 으로 폼 안에 렌더
+        const view = mountInForm(button({ type: 'button' }));
+        // When: 클릭한다
+        act(() => mustQuery(view.container, 'button').click());
+        // Then: submit 이 없다 — 위 케이스의 submit 기록이 배선 착시가 아님을 보인다
+        expect(view.submits).toEqual([]);
+    });
+    it.todo('BTN-04 기대 동작 (#620): type 을 넘기지 않으면 type="button" 으로 렌더해 폼을 제출하지 않는다');
+});
+/** 받은 width · height · color 를 속성으로 남기는 합성 아이콘 — 실제 아이콘의 SVG 반영은 아이콘 패키지 소관 */
+const makeIcon = (name) => {
+    const Icon = ({ width, height, color }) => createElement('svg', { 'data-icon': name, width, height, color });
+    return Icon;
+};
+const LeadingIcon = makeIcon('leading');
+const TrailingIcon = makeIcon('trailing');
+/** 기본 아이콘 크기(12 · 14 · 16 · 20)와 겹치지 않는 지정 크기 */
+const CUSTOM_ICON_SIZE = 18;
+/** xs 버튼 기본 아이콘 크기 — 일반 14 · onlyIcon 16 */
+const XS_ICON_SIZE = 14;
+const XS_ICON_ONLY_SIZE = 16;
+const mustIcon = (root, name) => mustQuery(root, `[data-icon="${name}"]`);
+describe('Button — loading (BTN-01)', () => {
+    it.each(['primary', 'secondary', 'secondary-gray', 'destructive'])('BTN-01 로딩 가능 hierarchy %s 는 loading 이면 스피너 · disabled · aria-busy 를 켠다', (hierarchy) => {
+        const view = mount(button({ hierarchy, loading: true }));
+        const element = mustQuery(view.container, 'button');
+        expect(element.querySelector('.ncua-btn__spinner')).not.toBeNull();
+        expect(element.disabled).toBe(true);
+        expect(element.getAttribute('aria-busy')).toBe('true');
+        expect(element.classList.contains('is-loading')).toBe(true);
+    });
+    it('BTN-01 loading 중에는 leadingIcon 자리를 스피너가 대신하고 trailingIcon 은 유지한다', () => {
+        const view = mount(button({
+            hierarchy: 'primary',
+            loading: true,
+            leadingIcon: { type: 'icon', icon: LeadingIcon },
+            trailingIcon: { type: 'icon', icon: TrailingIcon },
+        }));
+        const element = mustQuery(view.container, 'button');
+        expect(element.firstElementChild?.classList.contains('ncua-btn__spinner')).toBe(true);
+        expect(element.querySelector('[data-icon="leading"]')).toBeNull();
+        expect(element.lastElementChild?.getAttribute('data-icon')).toBe('trailing');
+    });
+    it.each([
+        ['로딩 불가 hierarchy(tertiary)', { hierarchy: 'tertiary' }],
+        ['onlyIcon', { hierarchy: 'primary', onlyIcon: true }],
+    ])('BTN-01 %s 이면 loading 을 무시한다', (_name, props) => {
+        const view = mount(button({ ...props, loading: true }));
+        const element = mustQuery(view.container, 'button');
+        expect(element.querySelector('.ncua-btn__spinner')).toBeNull();
+        expect(element.disabled).toBe(false);
+        expect(element.hasAttribute('aria-busy')).toBe(false);
+    });
+});
+describe('Button — 슬롯 (BTN-02)', () => {
+    it.each([
+        ['지정 size 가 우선', { size: CUSTOM_ICON_SIZE }, {}, CUSTOM_ICON_SIZE],
+        ['일반 버튼 기본 크기', {}, {}, XS_ICON_SIZE],
+        ['onlyIcon 기본 크기', {}, { onlyIcon: true }, XS_ICON_ONLY_SIZE],
+    ])('BTN-02 icon 슬롯 크기: %s', (_name, slotExtra, buttonExtra, expected) => {
+        const view = mount(button({ ...buttonExtra, leadingIcon: { type: 'icon', icon: LeadingIcon, ...slotExtra } }));
+        const icon = mustIcon(view.container, 'leading');
+        expect([icon.getAttribute('width'), icon.getAttribute('height')]).toEqual([String(expected), String(expected)]);
+    });
+    it.each([
+        ['color 지정 시 COLOR 값', 'gray700', COLOR.gray700],
+        ['color 생략 시 없음', undefined, null],
+    ])('BTN-02 icon 슬롯 색: %s', (_name, color, expected) => {
+        const view = mount(button({ leadingIcon: { type: 'icon', icon: LeadingIcon, color } }));
+        expect(mustIcon(view.container, 'leading').getAttribute('color')).toBe(expected);
+    });
+    it.each([
+        ['지정 size', { type: 'dot', color: 'error', size: 'lg' }, 'sm', 'ncua-dot--lg'],
+        ['size 생략 시 버튼 크기 매핑(sm → md)', { type: 'dot', color: 'error' }, 'sm', 'ncua-dot--md'],
+    ])('BTN-02 dot 슬롯: %s', (_name, slot, size, expectedClass) => {
+        // size 생략은 타입 밖이라 캐스팅한다 — `slot.size ?? dotSize[size]` 폴백 경로
+        const view = mount(button({ size, leadingIcon: slot }));
+        const dot = mustQuery(view.container, '.ncua-dot');
+        expect(Array.from(dot.classList)).toEqual(expect.arrayContaining(['ncua-dot--error', expectedClass]));
+    });
+    it('BTN-02 custom 슬롯은 children 을 그대로 그리고 trailingIcon 도 슬롯 규칙을 따른다', () => {
+        const view = mount(button({
+            leadingIcon: { type: 'custom', children: createElement('i', { className: 'custom-slot' }) },
+            trailingIcon: { type: 'icon', icon: TrailingIcon },
+        }));
+        const element = mustQuery(view.container, 'button');
+        expect(element.querySelector('.custom-slot')).not.toBeNull();
+        expect(element.lastElementChild?.getAttribute('data-icon')).toBe('trailing');
+    });
+});
+describe('Button — 클래스 · ref · 나머지 props (BTN-03)', () => {
+    it('BTN-03 size · hierarchy · onlyIcon · underline · className 을 클래스로 반영하고 onlyIcon 이면 label 을 숨긴다', () => {
+        const view = mount(button({ size: 'md', hierarchy: 'primary', onlyIcon: true, underline: true, className: 'custom-btn' }));
+        const element = mustQuery(view.container, 'button');
+        expect(Array.from(element.classList)).toEqual(expect.arrayContaining([
+            'ncua-btn',
+            'ncua-btn--md',
+            'ncua-btn--primary',
+            'only-icon',
+            'has-underline',
+            'custom-btn',
+        ]));
+        expect(element.querySelector('.ncua-btn__label')).toBeNull();
+    });
+    it('BTN-03 기본값: xs · secondary-gray, label 표시, disabled 면 is-disable', () => {
+        const view = mount(button({ disabled: true }));
+        const element = mustQuery(view.container, 'button');
+        expect(Array.from(element.classList)).toEqual(expect.arrayContaining(['ncua-btn--xs', 'ncua-btn--secondary-gray', 'is-disable']));
+        expect(mustQuery(element, '.ncua-btn__label').textContent).toBe(LABEL);
+    });
+    it('BTN-03 ref 는 button 요소를 가리키고 나머지 props · children 을 전달한다', () => {
+        const ref = createRef();
+        const onClick = vi.fn();
+        const view = mount(createElement(Button, { label: LABEL, ref, onClick, 'aria-label': '저장하기' }, createElement('span', { className: 'extra' })));
+        const element = mustQuery(view.container, 'button');
+        act(() => element.click());
+        expect(ref.current).toBe(element);
+        expect(element.getAttribute('aria-label')).toBe('저장하기');
+        expect(element.querySelector('.extra')).not.toBeNull();
+        expect(onClick).toHaveBeenCalled();
+    });
+});

package/dist/temp/src/components/action/button-group/__tests__/ButtonGroup.test.d.ts

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