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

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 {};

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

@@ -0,0 +1,162 @@
+// @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 { COLOR } from '../../../../../constant/color';
+import { ButtonGroup } from '../ButtonGroup';
+// React 18에서 act() 사용 시 필요한 플래그 (미설정 시 console.error 경고 발생)
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+/** 기본 아이콘 크기(12 · 16 · 20)와 겹치지 않는 지정 크기 */
+const CUSTOM_ICON_SIZE = 18;
+/** xs Item 의 기본 아이콘 크기 */
+const XS_ICON_SIZE = 16;
+/** md 그룹의 기본 아이콘 크기 */
+const MD_ICON_SIZE = 20;
+/** 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 };
+};
+/** form 으로 감싸 마운트하고, 제출 이벤트를 기록한다 (제출은 막는다) */
+const mountInForm = (child) => {
+    const submits = [];
+    const onSubmit = (event) => {
+        event.preventDefault();
+        submits.push(event.nativeEvent);
+    };
+    return { ...mount(createElement('form', { onSubmit }, child)), submits };
+};
+const group = (props, ...children) => 
+// children 은 가변 인자로 넘겨 React 가 배열 key 경고 없이 개별 자식으로 받게 한다
+createElement(ButtonGroup, props, ...children);
+const item = (props) => createElement(ButtonGroup.Item, props);
+const mustQuery = (root, selector) => {
+    const found = root.querySelector(selector);
+    if (!found)
+        throw new Error(`요소를 찾을 수 없습니다: ${selector}`);
+    return found;
+};
+const items = (root) => Array.from(root.querySelectorAll('.ncua-button-group__item'));
+/** 받은 width · height · color 를 속성으로 남기는 합성 아이콘 */
+const SyntheticIcon = ({ width, height, color }) => createElement('svg', { 'data-icon': '', width, height, color });
+describe('ButtonGroup — 그룹 → Item 전파 (BGR-01)', () => {
+    it('BGR-01 그룹 onlyIcon 은 Item 값을 덮어 label 을 숨기고 is-only-icon 을 붙인다', () => {
+        const view = mount(group({ onlyIcon: true }, item({ label: '보기', onlyIcon: false })));
+        const [button] = items(view.container);
+        expect(button.classList.contains('is-only-icon')).toBe(true);
+        expect(button.textContent).toBe('');
+    });
+    it('BGR-01 그룹 size 는 Item size 를 덮어 아이콘 기본 크기를 정한다', () => {
+        const view = mount(group({ size: 'md' }, item({ label: '보기', size: 'xxs', icon: { type: 'icon', icon: SyntheticIcon } })));
+        expect(mustQuery(view.container, '[data-icon]').getAttribute('width')).toBe(String(MD_ICON_SIZE));
+    });
+    it.each([
+        ['그룹 disabled', { disabled: true }, { label: 'A' }, true],
+        ['Item disabled', {}, { label: 'A', disabled: true }, true],
+        ['둘 다 아님', {}, { label: 'A' }, false],
+    ])('BGR-01 %s → Item disabled %s', (_name, groupProps, itemProps, expected) => {
+        const view = mount(group(groupProps, item(itemProps)));
+        expect(items(view.container).map((button) => button.disabled)).toEqual([expected]);
+    });
+    it('BGR-01 React 요소가 아닌 자식(문자열 · null)은 렌더하지 않는다', () => {
+        const view = mount(group({}, '문자열 자식', null, item({ label: 'A' })));
+        const root = mustQuery(view.container, '.ncua-button-group');
+        expect(root.textContent).toBe('A');
+        expect(root.children.length).toBe(1);
+    });
+});
+describe('ButtonGroup.Item — 슬롯 · 위치 · 상태 (BGR-02)', () => {
+    it.each([
+        ['지정 size 가 우선', { size: CUSTOM_ICON_SIZE }, CUSTOM_ICON_SIZE],
+        ['기본 xs 크기', {}, XS_ICON_SIZE],
+    ])('BGR-02 icon 슬롯 크기: %s', (_name, slotExtra, expected) => {
+        const view = mount(item({ label: 'A', icon: { type: 'icon', icon: SyntheticIcon, ...slotExtra } }));
+        const icon = mustQuery(view.container, '[data-icon]');
+        expect([icon.getAttribute('width'), icon.getAttribute('height')]).toEqual([String(expected), String(expected)]);
+    });
+    it.each([
+        ['color 지정 시 COLOR 값', 'gray700', COLOR.gray700],
+        ['color 생략 시 currentColor', undefined, 'currentColor'],
+    ])('BGR-02 icon 슬롯 색: %s', (_name, color, expected) => {
+        const view = mount(item({ label: 'A', icon: { type: 'icon', icon: SyntheticIcon, color } }));
+        expect(mustQuery(view.container, '[data-icon]').getAttribute('color')).toBe(expected);
+    });
+    it.each([
+        ['지정 size', { type: 'dot', color: 'success', size: 'lg' }, 'xs', 'ncua-dot--lg'],
+        ['size 생략 시 Item 크기 매핑(md → md)', { type: 'dot', color: 'success' }, 'md', 'ncua-dot--md'],
+    ])('BGR-02 dot 슬롯: %s', (_name, slot, size, expectedClass) => {
+        // size 생략은 타입 밖이라 캐스팅한다 — `icon.size ?? dotSize[size]` 폴백 경로
+        const view = mount(item({ label: 'A', size, icon: slot }));
+        expect(mustQuery(view.container, '.ncua-dot').classList.contains(expectedClass)).toBe(true);
+    });
+    it('BGR-02 custom 슬롯은 children 을 그린다', () => {
+        const view = mount(item({ label: 'A', icon: { type: 'custom', children: createElement('i', { className: 'custom-slot' }) } }));
+        expect(view.container.querySelector('.custom-slot')).not.toBeNull();
+    });
+    it.each([
+        ['기본(leading)', undefined, 'first'],
+        ['trailing', 'trailing', 'last'],
+    ])('BGR-02 position %s 이면 아이콘이 label 의 %s 쪽에 온다', (_name, position, side) => {
+        const view = mount(item({ label: 'A', icon: { type: 'icon', icon: SyntheticIcon, position }, children: createElement('b') }));
+        const [button] = items(view.container);
+        const edge = side === 'first' ? button.firstChild : button.lastChild;
+        expect(edge).toBe(mustQuery(button, '[data-icon]'));
+    });
+    it('BGR-02 isCurrent · className · children 을 반영하고 클릭은 onClick 을 부른다', () => {
+        const onClick = vi.fn();
+        const view = mount(item({ label: 'A', isCurrent: true, className: 'custom-item', onClick, children: createElement('b') }));
+        const [button] = items(view.container);
+        act(() => button.click());
+        expect([button.classList.contains('is-current'), button.classList.contains('custom-item')]).toEqual([true, true]);
+        expect(button.querySelector('b')).not.toBeNull();
+        expect(onClick).toHaveBeenCalled();
+    });
+    it('BGR-02 Item 은 type="button" 이라 폼 안에서 클릭해도 제출하지 않는다', () => {
+        const view = mountInForm(item({ label: 'A' }));
+        act(() => items(view.container)[0].click());
+        expect(items(view.container)[0].getAttribute('type')).toBe('button');
+        expect(view.submits).toEqual([]);
+    });
+    it('BGR-02 (대조) Item 에 type="submit" 을 넘기면 폼을 제출한다 — 위 단언이 공허하지 않음', () => {
+        const view = mountInForm(item({ label: 'A', type: 'submit' }));
+        act(() => items(view.container)[0].click());
+        expect(view.submits).toHaveLength(1);
+    });
+});
+describe('ButtonGroup — Item onlyIcon 계약 (BGR-04)', () => {
+    it('BGR-04 그룹이 onlyIcon 을 생략하면 Item 의 onlyIcon true 가 그룹 기본값 false 로 덮여 label 이 보인다', () => {
+        // 현재 동작 고정 — 결함 후보: #627 BGR-04 (문서의 Item onlyIcon 이 그룹 기본값에 항상 덮여 효과 없음)
+        const view = mount(group({}, item({ label: '보기', onlyIcon: true })));
+        const [button] = items(view.container);
+        expect([button.classList.contains('is-only-icon'), button.textContent]).toEqual([false, '보기']);
+    });
+    it.todo('BGR-04 기대 동작: 그룹이 onlyIcon 을 지정하지 않으면 Item 의 onlyIcon 이 적용된다 (또는 문서에서 Item onlyIcon 제거)');
+});
+describe('ButtonGroup — 그룹 클래스 (BGR-03)', () => {
+    it('BGR-03 기본: --xs · has-border, full-width 없음', () => {
+        const view = mount(group({}, item({ label: 'A' })));
+        const root = mustQuery(view.container, '.ncua-button-group');
+        expect(['ncua-button-group--xs', 'has-border', 'full-width'].map((name) => root.classList.contains(name))).toEqual([
+            true,
+            true,
+            false,
+        ]);
+    });
+    it('BGR-03 size · hasBorder false · fullWidth · className 을 반영한다', () => {
+        const view = mount(group({ size: 'sm', hasBorder: false, fullWidth: true, className: 'custom-group' }, item({ label: 'A' })));
+        const root = mustQuery(view.container, '.ncua-button-group');
+        expect(['ncua-button-group--sm', 'has-border', 'full-width', 'custom-group'].map((name) => root.classList.contains(name))).toEqual([true, false, true, true]);
+    });
+});

package/dist/temp/src/components/data-display/data-grid/__tests__/DataGrid.test.d.ts

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