@ncds/ui-admin 1.8.15 → 1.8.17

package/dist/temp/src/components/forms-and-input/image-file-input/__tests__/ImageFileInput.test.js

@@ -0,0 +1,435 @@
+// @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 { ImageFileInput, ImageFileInputErrorType } from '../ImageFileInput';
+const mounted = [];
+function mount(props) {
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    const root = createRoot(container);
+    act(() => {
+        root.render(createElement(ImageFileInput, props));
+    });
+    mounted.push({ root, container });
+    return container;
+}
+const previewImages = (container) => Array.from(container.querySelectorAll('.ncua-image-file-input__preview-image'));
+const emptySlot = (container) => container.querySelector('.ncua-image-file-input__empty-slot-wrapper');
+const makeFile = (name, size = 10) => new File([new Uint8Array(size)], name, { type: 'image/jpeg' });
+/**
+ * 숨겨진 file input에 파일을 실어 change 이벤트를 발생시킨다.
+ * jsdom에는 파일 선택 UI가 없어 files 프로퍼티를 직접 정의해야 한다.
+ */
+function selectFiles(container, filesToSelect) {
+    const input = container.querySelector('input[type="file"]');
+    if (!input)
+        throw new Error('file input을 찾지 못했습니다');
+    Object.defineProperty(input, 'files', {
+        configurable: true,
+        value: {
+            ...filesToSelect,
+            length: filesToSelect.length,
+            item: (index) => filesToSelect[index] ?? null,
+            [Symbol.iterator]: function* () {
+                yield* filesToSelect;
+            },
+        },
+    });
+    act(() => {
+        input.dispatchEvent(new Event('change', { bubbles: true }));
+    });
+}
+afterEach(() => {
+    for (const { root, container } of mounted.splice(0)) {
+        act(() => {
+            root.unmount();
+        });
+        container.remove();
+    }
+    vi.restoreAllMocks();
+});
+describe('ImageFileInput — 저장된 이미지 URL 미리보기', () => {
+    it('uploadedFiles의 URL을 img src로 그대로 렌더한다 (fetch 없이)', () => {
+        const fetchSpy = vi.spyOn(globalThis, 'fetch');
+        const container = mount({
+            uploadedFiles: [{ fileName: 'saved.jpg', fileImageUrl: 'https://external.example.com/saved.jpg' }],
+        });
+        const images = previewImages(container);
+        expect(images).toHaveLength(1);
+        expect(images[0].getAttribute('src')).toBe('https://external.example.com/saved.jpg');
+        expect(fetchSpy).not.toHaveBeenCalled();
+    });
+    it('fileName을 img alt로 사용한다', () => {
+        const container = mount({
+            uploadedFiles: [{ fileName: '상품이미지.jpg', fileImageUrl: 'https://external.example.com/a.jpg' }],
+        });
+        expect(previewImages(container)[0].getAttribute('alt')).toBe('상품이미지.jpg');
+    });
+    it('여러 장을 전달한 순서대로 렌더한다', () => {
+        const container = mount({
+            maxFileCount: 5,
+            uploadedFiles: [
+                { fileName: 'a.jpg', fileImageUrl: 'https://external.example.com/a.jpg' },
+                { fileName: 'b.jpg', fileImageUrl: 'https://external.example.com/b.jpg' },
+            ],
+        });
+        expect(previewImages(container).map((img) => img.getAttribute('src'))).toEqual([
+            'https://external.example.com/a.jpg',
+            'https://external.example.com/b.jpg',
+        ]);
+    });
+    it('저장된 이미지를 삭제하면 남은 목록으로 onUploadedFilesChange를 호출한다', () => {
+        const onUploadedFilesChange = vi.fn();
+        const container = mount({
+            maxFileCount: 5,
+            uploadedFiles: [
+                { fileName: 'a.jpg', fileImageUrl: 'https://external.example.com/a.jpg' },
+                { fileName: 'b.jpg', fileImageUrl: 'https://external.example.com/b.jpg' },
+            ],
+            onUploadedFilesChange,
+        });
+        const removeButtons = container.querySelectorAll('.ncua-image-file-input__preview-remove-button');
+        expect(removeButtons).toHaveLength(2);
+        act(() => {
+            removeButtons[0].click();
+        });
+        expect(onUploadedFilesChange).toHaveBeenCalledTimes(1);
+        expect(onUploadedFilesChange).toHaveBeenCalledWith([
+            { fileName: 'b.jpg', fileImageUrl: 'https://external.example.com/b.jpg' },
+        ]);
+    });
+    // uploadedFiles는 value/onChange와 같은 controlled prop이다.
+    // 콜백을 넘기지 않으면 미리보기가 그대로 유지되는 것이 의도된 동작이며,
+    // 이 테스트는 "무반응이어도 괜찮다"가 아니라 그 계약을 고정하기 위한 것이다.
+    it('콜백 없이 uploadedFiles만 넘기면 삭제해도 미리보기가 유지된다 (controlled 계약)', () => {
+        const container = mount({
+            uploadedFiles: [{ fileName: 'a.jpg', fileImageUrl: 'https://external.example.com/a.jpg' }],
+        });
+        const removeButton = container.querySelector('.ncua-image-file-input__preview-remove-button');
+        act(() => {
+            removeButton?.click();
+        });
+        expect(previewImages(container)).toHaveLength(1);
+    });
+    it('같은 URL에 이름만 다른 항목이 있어도 key가 겹치지 않는다', () => {
+        // React 는 key 가 겹쳐도 DOM 에는 그려주고 console.error 로만 경고한다.
+        // 따라서 렌더 결과가 아니라 경고 발생 여부로 판정해야 한다.
+        const consoleError = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+        const sharedUrl = 'https://external.example.com/shared.jpg';
+        const container = mount({
+            maxFileCount: 5,
+            uploadedFiles: [
+                { fileName: 'first.jpg', fileImageUrl: sharedUrl },
+                { fileName: 'second.jpg', fileImageUrl: sharedUrl },
+            ],
+        });
+        expect(previewImages(container).map((img) => img.getAttribute('alt'))).toEqual(['first.jpg', 'second.jpg']);
+        expect(consoleError.mock.calls.flat(Number.POSITIVE_INFINITY).join(' ')).not.toContain('same key');
+    });
+    it('URL과 파일명이 모두 같은 항목이 둘이어도 key가 겹치지 않는다', () => {
+        const consoleError = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+        const same = { fileName: 'same.jpg', fileImageUrl: 'https://external.example.com/same.jpg' };
+        const container = mount({ maxFileCount: 5, uploadedFiles: [same, { ...same }] });
+        expect(previewImages(container)).toHaveLength(2);
+        expect(consoleError.mock.calls.flat(Number.POSITIVE_INFINITY).join(' ')).not.toContain('same key');
+    });
+    it('같은 파일명이 여러 개여도 클릭한 항목만 정확히 제거한다 (순번 아닌 항목 기준 삭제)', () => {
+        const onUploadedFilesChange = vi.fn();
+        const duplicated = [
+            { fileName: '같은이름.jpg', fileImageUrl: 'https://external.example.com/first.jpg' },
+            { fileName: '같은이름.jpg', fileImageUrl: 'https://external.example.com/second.jpg' },
+        ];
+        const container = mount({ maxFileCount: 5, uploadedFiles: duplicated, onUploadedFilesChange });
+        act(() => {
+            container.querySelectorAll('.ncua-image-file-input__preview-remove-button')[1].click();
+        });
+        expect(onUploadedFilesChange).toHaveBeenCalledWith([duplicated[0]]);
+    });
+});
+describe('ImageFileInput — URL 없는 항목 방어 (CDN/바닐라 등 타입 검사 밖 사용)', () => {
+    it('fileImageUrl이 비어 있으면 렌더하지 않는다', () => {
+        const container = mount({
+            maxFileCount: 3,
+            uploadedFiles: [
+                { fileName: 'a.jpg', fileImageUrl: 'https://external.example.com/a.jpg' },
+                { fileName: 'broken.jpg', fileImageUrl: '' },
+            ],
+        });
+        expect(previewImages(container).map((img) => img.getAttribute('src'))).toEqual([
+            'https://external.example.com/a.jpg',
+        ]);
+    });
+    it('fileImageUrl이 비어 있는 항목은 슬롯을 차지하지 않는다', () => {
+        const container = mount({
+            maxFileCount: 2,
+            uploadedFiles: [
+                { fileName: 'a.jpg', fileImageUrl: 'https://external.example.com/a.jpg' },
+                { fileName: 'broken.jpg', fileImageUrl: '' },
+            ],
+        });
+        // 유효한 1장 < maxFileCount 2 → 빈 슬롯이 남아야 한다
+        expect(emptySlot(container)).not.toBeNull();
+    });
+    it('삭제 시 렌더되지 않은 항목도 호출자 목록에 그대로 남긴다', () => {
+        const onUploadedFilesChange = vi.fn();
+        const broken = { fileName: 'broken.jpg', fileImageUrl: '' };
+        const container = mount({
+            maxFileCount: 3,
+            uploadedFiles: [{ fileName: 'a.jpg', fileImageUrl: 'https://external.example.com/a.jpg' }, broken],
+            onUploadedFilesChange,
+        });
+        act(() => {
+            container.querySelector('.ncua-image-file-input__preview-remove-button')?.click();
+        });
+        expect(onUploadedFilesChange).toHaveBeenCalledWith([broken]);
+    });
+});
+describe('ImageFileInput — object URL 해제', () => {
+    /** 리렌더를 반복해도 URL이 늘지 않는지 보기 위한 횟수 */
+    const REPEATED_RENDERS = 3;
+    const originalCreateObjectURL = URL.createObjectURL;
+    const originalRevokeObjectURL = URL.revokeObjectURL;
+    let createObjectURL;
+    let revokeObjectURL;
+    beforeEach(() => {
+        let issued = 0;
+        createObjectURL = vi.fn(() => `blob:mock/${++issued}`);
+        revokeObjectURL = vi.fn();
+        URL.createObjectURL = createObjectURL;
+        URL.revokeObjectURL = revokeObjectURL;
+    });
+    afterEach(() => {
+        URL.createObjectURL = originalCreateObjectURL;
+        URL.revokeObjectURL = originalRevokeObjectURL;
+    });
+    it('리렌더를 반복해도 파일당 object URL을 한 번만 만든다', () => {
+        const file = makeFile('a.jpg');
+        const container = document.createElement('div');
+        document.body.appendChild(container);
+        const root = createRoot(container);
+        for (let renderCount = 0; renderCount < REPEATED_RENDERS; renderCount++) {
+            act(() => {
+                root.render(createElement(ImageFileInput, { value: [file], onChange: () => undefined }));
+            });
+        }
+        expect(createObjectURL).toHaveBeenCalledTimes(1);
+        act(() => {
+            root.unmount();
+        });
+        container.remove();
+    });
+    it('언마운트하면 만들었던 object URL을 해제한다', () => {
+        const container = mount({ value: [makeFile('a.jpg')], onChange: () => undefined });
+        expect(createObjectURL).toHaveBeenCalledTimes(1);
+        for (const entry of mounted.splice(0)) {
+            act(() => {
+                entry.root.unmount();
+            });
+            entry.container.remove();
+        }
+        expect(revokeObjectURL).toHaveBeenCalledWith('blob:mock/1');
+        expect(container.isConnected).toBe(false);
+    });
+});
+describe('ImageFileInput — 파일 선택 시 저장된 이미지 반영', () => {
+    it('저장된 이미지를 포함해 maxFileCount를 초과하면 EXCEED_MAX_FILE_COUNT로 거른다', () => {
+        const onFail = vi.fn();
+        const onChange = vi.fn();
+        const container = mount({
+            maxFileCount: 2,
+            value: [],
+            onChange,
+            onFail,
+            uploadedFiles: [
+                { fileName: 'a.jpg', fileImageUrl: 'https://external.example.com/a.jpg' },
+                { fileName: 'b.jpg', fileImageUrl: 'https://external.example.com/b.jpg' },
+            ],
+        });
+        selectFiles(container, [makeFile('new.jpg')]);
+        expect(onFail).toHaveBeenCalledTimes(1);
+        expect(onFail.mock.calls[0][0][0].errorType).toBe(ImageFileInputErrorType.EXCEED_MAX_FILE_COUNT);
+        // 전량 반려이므로 목록을 건드리지 않는다
+        expect(onChange).not.toHaveBeenCalled();
+    });
+    it('저장된 이미지와 파일명이 같으면 ALREADY_UPLOADED로 거른다', () => {
+        const onFail = vi.fn();
+        const container = mount({
+            maxFileCount: 5,
+            value: [],
+            onChange: () => undefined,
+            onFail,
+            uploadedFiles: [{ fileName: 'same.jpg', fileImageUrl: 'https://external.example.com/same.jpg' }],
+        });
+        selectFiles(container, [makeFile('same.jpg')]);
+        expect(onFail).toHaveBeenCalledTimes(1);
+        expect(onFail.mock.calls[0][0][0].errorType).toBe(ImageFileInputErrorType.ALREADY_UPLOADED);
+    });
+    it('maxFileCount가 1이면 새 파일 선택 시 저장된 이미지도 비운다', () => {
+        const onUploadedFilesChange = vi.fn();
+        const onChange = vi.fn();
+        const container = mount({
+            maxFileCount: 1,
+            value: [],
+            onChange,
+            uploadedFiles: [{ fileName: 'old.jpg', fileImageUrl: 'https://external.example.com/old.jpg' }],
+            onUploadedFilesChange,
+        });
+        const picked = makeFile('new.jpg');
+        selectFiles(container, [picked]);
+        expect(onChange).toHaveBeenCalledWith([picked]);
+        expect(onUploadedFilesChange).toHaveBeenCalledWith([]);
+    });
+    it('maxFileCount가 1이면 저장된 이미지와 이름이 같아도 교체를 허용한다', () => {
+        const onFail = vi.fn();
+        const onChange = vi.fn();
+        const onUploadedFilesChange = vi.fn();
+        const container = mount({
+            maxFileCount: 1,
+            value: [],
+            onChange,
+            onFail,
+            uploadedFiles: [{ fileName: 'photo.jpg', fileImageUrl: 'https://external.example.com/photo.jpg' }],
+            onUploadedFilesChange,
+        });
+        const picked = makeFile('photo.jpg');
+        selectFiles(container, [picked]);
+        expect(onFail).not.toHaveBeenCalled();
+        expect(onChange).toHaveBeenCalledWith([picked]);
+        expect(onUploadedFilesChange).toHaveBeenCalledWith([]);
+    });
+    it('한 장짜리 교체 시 렌더되지 않은 항목은 호출자 목록에 남긴다', () => {
+        const onUploadedFilesChange = vi.fn();
+        const broken = { fileName: 'broken.jpg', fileImageUrl: '' };
+        const container = mount({
+            maxFileCount: 1,
+            value: [],
+            onChange: () => undefined,
+            uploadedFiles: [{ fileName: 'old.jpg', fileImageUrl: 'https://external.example.com/old.jpg' }, broken],
+            onUploadedFilesChange,
+        });
+        selectFiles(container, [makeFile('new.jpg')]);
+        expect(onUploadedFilesChange).toHaveBeenCalledWith([broken]);
+    });
+    it('저장된 이미지가 없으면 maxFileCount 1이어도 불필요하게 콜백을 호출하지 않는다', () => {
+        const onUploadedFilesChange = vi.fn();
+        const container = mount({
+            maxFileCount: 1,
+            value: [],
+            onChange: () => undefined,
+            uploadedFiles: [],
+            onUploadedFilesChange,
+        });
+        selectFiles(container, [makeFile('new.jpg')]);
+        expect(onUploadedFilesChange).not.toHaveBeenCalled();
+    });
+});
+describe('ImageFileInput — disabled 읽기 전용', () => {
+    const removeButtons = (container) => container.querySelectorAll('.ncua-image-file-input__preview-remove-button');
+    it('disabled면 저장된 이미지의 삭제 버튼을 렌더하지 않는다', () => {
+        const container = mount({
+            disabled: true,
+            maxFileCount: 3,
+            uploadedFiles: [{ fileName: 'a.jpg', fileImageUrl: 'https://external.example.com/a.jpg' }],
+        });
+        expect(previewImages(container)).toHaveLength(1); // 썸네일은 보인다
+        expect(removeButtons(container)).toHaveLength(0); // 삭제 아이콘은 미노출
+    });
+    it('disabled면 새로 고른 파일의 삭제 버튼도 렌더하지 않는다', () => {
+        const container = mount({
+            disabled: true,
+            maxFileCount: 3,
+            value: [makeFile('new.jpg')],
+            onChange: () => undefined,
+        });
+        expect(removeButtons(container)).toHaveLength(0);
+    });
+    it('disabled가 아니면 삭제 버튼을 렌더한다', () => {
+        const container = mount({
+            maxFileCount: 3,
+            uploadedFiles: [{ fileName: 'a.jpg', fileImageUrl: 'https://external.example.com/a.jpg' }],
+        });
+        expect(removeButtons(container)).toHaveLength(1);
+    });
+});
+describe('ImageFileInput — 전량 반려 시 기존 선택 보존', () => {
+    it('maxFileCount가 1일 때 모두 반려되면 이미 고른 파일을 유지한다', () => {
+        const already = makeFile('picked.jpg');
+        const onChange = vi.fn();
+        const onFail = vi.fn();
+        const container = mount({
+            maxFileCount: 1,
+            value: [already],
+            onChange,
+            onFail,
+        });
+        // 같은 파일을 다시 고르면 ALREADY_UPLOADED 로 전량 반려된다
+        selectFiles(container, [makeFile('picked.jpg')]);
+        expect(onFail).toHaveBeenCalledTimes(1);
+        expect(onFail.mock.calls[0][0][0].errorType).toBe(ImageFileInputErrorType.ALREADY_UPLOADED);
+        expect(onChange).not.toHaveBeenCalled(); // 빈 배열로 덮어쓰지 않는다
+    });
+    it('전량 반려되면 저장된 이미지도 비우지 않는다', () => {
+        const saved = { fileName: 'saved.jpg', fileImageUrl: 'https://external.example.com/saved.jpg' };
+        const onUploadedFilesChange = vi.fn();
+        const container = mount({
+            maxFileCount: 3,
+            value: [makeFile('picked.jpg')],
+            onChange: () => undefined,
+            uploadedFiles: [saved],
+            onUploadedFilesChange,
+            onFail: () => undefined,
+        });
+        selectFiles(container, [makeFile('picked.jpg')]);
+        expect(onUploadedFilesChange).not.toHaveBeenCalled();
+    });
+    it('일부만 통과하면 통과분만 반영한다', () => {
+        const already = makeFile('dup.jpg');
+        const onChange = vi.fn();
+        const container = mount({
+            maxFileCount: 5,
+            value: [already],
+            onChange,
+            onFail: () => undefined,
+        });
+        const fresh = makeFile('fresh.jpg');
+        selectFiles(container, [makeFile('dup.jpg'), fresh]);
+        expect(onChange).toHaveBeenCalledWith([already, fresh]);
+    });
+});
+describe('ImageFileInput — 저장된 이미지의 슬롯 수 합산', () => {
+    it('uploadedFiles가 maxFileCount를 채우면 빈 슬롯을 감춘다', () => {
+        const container = mount({
+            maxFileCount: 2,
+            uploadedFiles: [
+                { fileName: 'a.jpg', fileImageUrl: 'https://external.example.com/a.jpg' },
+                { fileName: 'b.jpg', fileImageUrl: 'https://external.example.com/b.jpg' },
+            ],
+        });
+        expect(emptySlot(container)).toBeNull();
+    });
+    it('maxFileCount에 여유가 있으면 빈 슬롯을 노출한다', () => {
+        const container = mount({
+            maxFileCount: 3,
+            uploadedFiles: [
+                { fileName: 'a.jpg', fileImageUrl: 'https://external.example.com/a.jpg' },
+                { fileName: 'b.jpg', fileImageUrl: 'https://external.example.com/b.jpg' },
+            ],
+        });
+        expect(emptySlot(container)).not.toBeNull();
+    });
+    it('maxFileCount가 없을 때 저장된 이미지가 있으면 빈 슬롯을 감춘다', () => {
+        const container = mount({
+            uploadedFiles: [{ fileName: 'a.jpg', fileImageUrl: 'https://external.example.com/a.jpg' }],
+        });
+        expect(emptySlot(container)).toBeNull();
+    });
+});
+describe('ImageFileInput — 기존 File 동작 회귀', () => {
+    it('uploadedFiles를 넘기지 않으면 빈 슬롯만 렌더한다', () => {
+        const container = mount({});
+        expect(previewImages(container)).toHaveLength(0);
+        expect(emptySlot(container)).not.toBeNull();
+    });
+});

package/dist/temp/src/components/forms-and-input/image-file-input/components/ImagePreview.d.ts

@@ -1,5 +1,23 @@
 export interface ImagePreviewProps {
-    file: File;
+    /**
+     * Newly selected file. Rendered via object URL.
+     * Either this or `imageUrl` must be provided.
+     */
+    file?: File;
+    /**
+     * URL of an image already stored on the server.
+     * Rendered directly, so no fetch or CORS handling is required.
+     */
+    imageUrl?: string;
+    /**
+     * Alternative text. Falls back to the file name when `file` is given.
+     */
+    alt?: string;
+    /**
+     * Read-only mode. The thumbnail stays visible but the remove button is not
+     * rendered, per DES-SPEC-013 §5.3 (Disabled — 삭제 아이콘 미노출).
+     */
+    disabled?: boolean;
     onRemove: () => void;
 }
-export declare const ImagePreview: ({ file, onRemove }: ImagePreviewProps) => import("react/jsx-runtime").JSX.Element;
+export declare const ImagePreview: ({ file, imageUrl, alt, disabled, onRemove }: ImagePreviewProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/temp/src/components/forms-and-input/image-file-input/components/ImagePreview.js

@@ -1,6 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Trash03 } from '@ncds/ui-admin-icon';
+import { useObjectUrl } from '../../../../hooks/useObjectUrl';
 import { Button } from '../../../action/button';
-export const ImagePreview = ({ file, onRemove }) => {
-    return (_jsxs("div", { className: "ncua-image-file-input__preview-container", children: [_jsx("img", { className: "ncua-image-file-input__preview-image", src: URL.createObjectURL(file), alt: file.name }), _jsx(Button, { size: "sm", hierarchy: "text", onlyIcon: true, leadingIcon: { type: 'icon', icon: Trash03, color: 'gray200' }, label: "Remove image", onClick: onRemove, className: "ncua-image-file-input__preview-remove-button" })] }));
+export const ImagePreview = ({ file, imageUrl, alt, disabled, onRemove }) => {
+    const objectUrl = useObjectUrl(file);
+    const src = file ? objectUrl : imageUrl;
+    if (!src)
+        return null;
+    return (_jsxs("div", { className: "ncua-image-file-input__preview-container", children: [_jsx("img", { className: "ncua-image-file-input__preview-image", src: src, alt: alt ?? file?.name ?? '' }), !disabled && (_jsx(Button, { size: "sm", hierarchy: "text", onlyIcon: true, leadingIcon: { type: 'icon', icon: Trash03, color: 'gray200' }, label: "Remove image", onClick: onRemove, className: "ncua-image-file-input__preview-remove-button" }))] }));
 };

package/dist/temp/src/hooks/__tests__/useObjectUrl.test.d.ts

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

package/dist/temp/src/hooks/__tests__/useObjectUrl.test.js

@@ -0,0 +1,96 @@
+// @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 { useObjectUrl } from '../useObjectUrl';
+const originalCreateObjectURL = URL.createObjectURL;
+const originalRevokeObjectURL = URL.revokeObjectURL;
+let createObjectURL;
+let revokeObjectURL;
+beforeEach(() => {
+    let issued = 0;
+    createObjectURL = vi.fn(() => `blob:mock/${++issued}`);
+    revokeObjectURL = vi.fn();
+    URL.createObjectURL = createObjectURL;
+    URL.revokeObjectURL = revokeObjectURL;
+});
+const mounted = [];
+afterEach(() => {
+    for (const { root, container } of mounted.splice(0)) {
+        act(() => {
+            root.unmount();
+        });
+        container.remove();
+    }
+    URL.createObjectURL = originalCreateObjectURL;
+    URL.revokeObjectURL = originalRevokeObjectURL;
+});
+/** 내용은 검증 대상이 아니므로 최소 크기만 채운다 */
+const DUMMY_FILE_BYTES = 4;
+const makeFile = (name) => new File([new Uint8Array(DUMMY_FILE_BYTES)], name, { type: 'image/jpeg' });
+/** 훅 결과를 data-url 속성으로 노출하는 관찰용 컴포넌트 */
+const Probe = ({ file }) => createElement('span', { 'data-url': useObjectUrl(file) ?? '' });
+function renderProbe(file) {
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    const root = createRoot(container);
+    const render = (nextFile) => {
+        act(() => {
+            root.render(createElement(Probe, { file: nextFile }));
+        });
+    };
+    render(file);
+    mounted.push({ root, container });
+    const currentUrl = () => container.querySelector('span')?.getAttribute('data-url');
+    const unmount = () => {
+        act(() => {
+            root.unmount();
+        });
+        const index = mounted.findIndex((entry) => entry.root === root);
+        mounted.splice(index, 1);
+        container.remove();
+    };
+    return { render, currentUrl, unmount };
+}
+describe('useObjectUrl', () => {
+    it('파일을 주면 object URL을 만들어 반환한다', () => {
+        const probe = renderProbe(makeFile('a.jpg'));
+        expect(createObjectURL).toHaveBeenCalledTimes(1);
+        expect(probe.currentUrl()).toBe('blob:mock/1');
+    });
+    it('같은 파일로 여러 번 리렌더해도 URL을 한 번만 만든다', () => {
+        const file = makeFile('a.jpg');
+        const probe = renderProbe(file);
+        probe.render(file);
+        probe.render(file);
+        probe.render(file);
+        expect(createObjectURL).toHaveBeenCalledTimes(1);
+        expect(revokeObjectURL).not.toHaveBeenCalled();
+    });
+    it('언마운트하면 만들었던 URL을 해제한다', () => {
+        const probe = renderProbe(makeFile('a.jpg'));
+        expect(revokeObjectURL).not.toHaveBeenCalled();
+        probe.unmount();
+        expect(revokeObjectURL).toHaveBeenCalledTimes(1);
+        expect(revokeObjectURL).toHaveBeenCalledWith('blob:mock/1');
+    });
+    it('파일이 바뀌면 이전 URL을 해제하고 새로 만든다', () => {
+        const probe = renderProbe(makeFile('a.jpg'));
+        probe.render(makeFile('b.jpg'));
+        expect(createObjectURL).toHaveBeenCalledTimes(2);
+        expect(revokeObjectURL).toHaveBeenCalledWith('blob:mock/1');
+        expect(probe.currentUrl()).toBe('blob:mock/2');
+    });
+    it('파일이 없으면 URL을 만들지 않는다', () => {
+        const probe = renderProbe(undefined);
+        expect(createObjectURL).not.toHaveBeenCalled();
+        expect(probe.currentUrl()).toBe('');
+    });
+    it('파일을 없애면 이전 URL을 해제한다', () => {
+        const probe = renderProbe(makeFile('a.jpg'));
+        probe.render(undefined);
+        expect(revokeObjectURL).toHaveBeenCalledWith('blob:mock/1');
+        expect(probe.currentUrl()).toBe('');
+    });
+});

package/dist/temp/src/hooks/index.d.ts

@@ -4,3 +4,4 @@ export * from './useFloatingPosition';
 export * from './useIsomorphicLayoutEffect';
 export * from './useMediaQuery';
 export * from './useMergeRefs';
+export * from './useObjectUrl';

package/dist/temp/src/hooks/index.js

@@ -6,3 +6,4 @@ export * from './useFloatingPosition';
 export * from './useIsomorphicLayoutEffect';
 export * from './useMediaQuery';
 export * from './useMergeRefs';
+export * from './useObjectUrl';

package/dist/temp/src/hooks/useObjectUrl.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Creates an object URL for a file and revokes it when the file changes
+ * or the component unmounts.
+ *
+ * Calling `URL.createObjectURL` inline while rendering mints a new blob URL on
+ * every re-render and never releases it, so the browser holds every one of them
+ * for the lifetime of the document. Creating it in an effect gives us a cleanup
+ * hook to revoke on.
+ *
+ * A layout effect is used so the URL is in place before the browser paints —
+ * with a plain effect the image would blink out for a frame whenever the
+ * component remounts (for example when a sibling is removed and keys shift).
+ *
+ * Returns `null` while no file is given.
+ */
+export declare const useObjectUrl: (file?: File) => string | null;

package/dist/temp/src/hooks/useObjectUrl.js

@@ -0,0 +1,32 @@
+import { useState } from 'react';
+import { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect';
+/**
+ * Creates an object URL for a file and revokes it when the file changes
+ * or the component unmounts.
+ *
+ * Calling `URL.createObjectURL` inline while rendering mints a new blob URL on
+ * every re-render and never releases it, so the browser holds every one of them
+ * for the lifetime of the document. Creating it in an effect gives us a cleanup
+ * hook to revoke on.
+ *
+ * A layout effect is used so the URL is in place before the browser paints —
+ * with a plain effect the image would blink out for a frame whenever the
+ * component remounts (for example when a sibling is removed and keys shift).
+ *
+ * Returns `null` while no file is given.
+ */
+export const useObjectUrl = (file) => {
+    const [objectUrl, setObjectUrl] = useState(null);
+    useIsomorphicLayoutEffect(() => {
+        if (!file) {
+            setObjectUrl(null);
+            return;
+        }
+        const createdUrl = URL.createObjectURL(file);
+        setObjectUrl(createdUrl);
+        return () => {
+            URL.revokeObjectURL(createdUrl);
+        };
+    }, [file]);
+    return objectUrl;
+};

package/dist/types/src/components/forms-and-input/file-input/FileInput.d.ts

@@ -57,5 +57,13 @@ export interface FileInputProps extends Omit<InputBaseProps, 'clearText' | 'onCl
      * Hint text to display
      */
     hintText?: string;
+    /**
+     * Whether to render the built-in file tag list
+     *
+     * Set to `false` when the file list is rendered outside the component —
+     * the selected files still arrive through `onChange` / `onFileSelect`, and
+     * file count/duplicate validation keeps working.
+     */
+    showFileTags?: boolean;
 }
 export declare const FileInput: import("react").ForwardRefExoticComponent<FileInputProps & import("react").RefAttributes<HTMLInputElement>>;

package/dist/types/src/components/forms-and-input/file-input/__tests__/FileInput.test.d.ts

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