@ihabdevteam/core 0.8.0

package/dist/packages/core/src/components/Effect/EffectPartyPopper.js

@@ -0,0 +1,298 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef } from "react";
+import { createPortal } from "react-dom";
+import "./EffectPartyPopper.css";
+// use only the app's two CSS variables for colors
+const COLORS = ["var(--color-main)", "var(--color-sub)"];
+/** @public */
+export default function EffectPartyPopper({ active = false, count = 40, duration = 2000, strength = 1, // multiplier for speed/spread
+onComplete, trigger = 0, }) {
+    // particle definitions (no CSS animations) - computed once per `count`
+    const pieces = useMemo(() => {
+        const leftCount = Math.floor(count / 2);
+        const rightCount = count - leftCount;
+        const make = (n, side) => Array.from({ length: n }).map((_, i) => {
+            const sizeBase = 6 + Math.random() * 12; // px
+            // slightly smaller, less variance for a cleaner look: cap growth vs strength
+            const size = Math.round(Math.min(18, sizeBase * Math.min(1.5, 1 + strength * 0.4)));
+            const color = COLORS[Math.floor(Math.random() * COLORS.length)];
+            const delay = Math.random() * 300; // ms
+            // speed and angle produce an upward/outward burst
+            const speed = (360 + Math.random() * 260) * strength * 1.2; // px/s (amplified)
+            // left launcher -> shoot to right-top; right launcher -> shoot to left-top
+            // bias angles toward more vertical for stronger upward motion
+            const angleDeg = side === "left"
+                ? -95 + Math.random() * 40 // -95 .. -55 deg (up-right-ish)
+                : -85 - Math.random() * 40; // -85 .. -125 deg (up-left-ish)
+            const angle = (angleDeg * Math.PI) / 180;
+            const vx = Math.cos(angle) * speed;
+            // amplify vertical component for stronger upward thrust
+            const vy = Math.sin(angle) * speed * 1.35;
+            const angularVel = (Math.random() * 720 - 360); // deg/s
+            // life: slightly longer average and less variance for cleaner visual
+            const life = (1200 + Math.random() * 3000) * Math.min(1.6, 1 + strength * 0.3); // ms
+            const borderRadius = Math.random() > 0.7 ? "50%" : "3px";
+            return {
+                id: `${side}-${i}`,
+                side,
+                size,
+                color,
+                delay,
+                vx,
+                vy,
+                angularVel,
+                life,
+                borderRadius,
+            };
+        });
+        return [...make(leftCount, "left"), ...make(rightCount, "right")];
+    }, [count, strength]);
+    const containerRef = useRef(null);
+    const nodesRef = useRef({});
+    const rafRef = useRef(null);
+    // onComplete를 effect deps에 넣으면 부모가 인라인 콜백을 새로 만들며 리렌더할 때마다
+    // 애니메이션 effect가 재실행돼 파티클이 처음부터 다시 터진다 — ref로 최신 콜백만 유지한다.
+    const onCompleteRef = useRef(onComplete);
+    useEffect(() => { onCompleteRef.current = onComplete; }, [onComplete]);
+    // 300ms 폴백으로 body에 직접 붙인 컨테이너 — 언마운트 시 제거해야 잔류 DOM이 안 쌓인다.
+    const fallbackContainerRef = useRef(null);
+    // 폭죽을 그릴 자리. **우리가 만든 컨테이너만** 다시 쓴다 — 클래스 이름만 보고 아무 `.app-effect`나
+    // 집으면, 소비처가 레이아웃 안에 같은 이름의 래퍼를 두고 있을 때 그쪽이 먼저 걸린다. 그런 요소는
+    // 대개 position:static 에 폭이 0이라 (1) 모달·오버레이 뒤로 깔려 아무것도 안 보이고
+    // (2) 발사 원점을 그 rect 로 잡는 아래 코드 때문에 좌우 양쪽이 화면 왼쪽 끝에 겹쳐 터진다.
+    // 그래서 표식(data-ihab-effect-root)을 붙여 두고 그 표식으로만 찾는다.
+    const mountElRef = useRef(null);
+    const getOrCreateMount = () => {
+        if (typeof document === 'undefined')
+            return null;
+        let el = document.querySelector('[data-ihab-effect-root]');
+        if (!el) {
+            el = document.createElement('div');
+            el.className = 'app-effect';
+            el.dataset.ihabEffectRoot = '';
+            // ensure it covers viewport and doesn't capture events
+            el.style.position = 'fixed';
+            el.style.inset = '0';
+            el.style.pointerEvents = 'none';
+            el.style.zIndex = '99998';
+            document.body.appendChild(el);
+        }
+        return el;
+    };
+    // portal target(mountElRef)은 아래 렌더링에서 즉시 사용되어야 하므로 effect로 옮길 수 없다 — 최초 1회만 지연 초기화
+    // eslint-disable-next-line react-hooks/refs
+    if (typeof document !== 'undefined' && mountElRef.current == null)
+        mountElRef.current = getOrCreateMount();
+    useEffect(() => {
+        if (!active)
+            return;
+        // 움직임 최소화를 켠 사용자에게는 화면을 가로지르는 물리 애니메이션을 재생하지 않는다.
+        // CSS의 전역 reduce 규칙(styles.css)은 requestAnimationFrame 기반인 이 효과를 막지 못한다.
+        if (typeof window !== 'undefined' && window.matchMedia?.('(prefers-reduced-motion: reduce)').matches) {
+            onCompleteRef.current?.();
+            return;
+        }
+        // production: no debug logging
+        const gravity = 1200; // px/s^2 (pulls downward) - reduced for longer arcs
+        const start = performance.now();
+        // compute origin relative to mount element if present
+        const rect = mountElRef.current && mountElRef.current !== document.body ? mountElRef.current.getBoundingClientRect() : null;
+        const off = Math.max(60, (window.innerHeight || 800) * 0.05);
+        const sideOffset = (w) => Math.max(40, (w || window.innerWidth) * 0.02);
+        // ── 화면 크기에 맞춰 발사 속도를 맞춘다 ────────────────────────────────
+        // 속도는 px/s 고정값이라 그대로 두면 화면이 클수록 상대적으로 낮게 뜬다 — 같은
+        // 포물선이 폰에서는 화면 절반까지 오르지만 데스크톱에서는 아래쪽에만 머문다.
+        // 그래서 "화면 높이의 72%까지 오른다"를 목표로 잡고 필요한 초기 속도를 역산한다.
+        // (등가속도: 정점 높이 h = v² / 2g  →  v = √(2gh))
+        const viewW = rect?.width || window.innerWidth || 375;
+        const viewH = rect?.height || window.innerHeight || 812;
+        const median = (xs) => {
+            const s = [...xs].sort((a, b) => a - b);
+            return s[Math.floor(s.length / 2)] || 1;
+        };
+        // 파티클마다 속도가 다른 게 이 효과의 생김새라 개별 값을 목표치로 덮어쓰지 않고,
+        // 무리 전체에 같은 배율을 곱해 흩어진 정도는 그대로 둔다.
+        const vyTypical = median(pieces.map(p => Math.abs(p.vy)));
+        const vxTypical = median(pieces.map(p => Math.abs(p.vx)));
+        // 발사점이 화면 아래 off 만큼 바깥이라 그만큼 더 올라와야 화면 안에서 72%가 된다.
+        const speedY = Math.sqrt(2 * gravity * (viewH * 0.72 + off)) / vyTypical;
+        // 가로는 모서리에서 쏴 화면 가운데쯤을 지나게 — 정점까지 걸리는 시간(t = v/g) 동안
+        // 폭의 절반을 가로지를 속도를 구한다.
+        const apexSec = (vyTypical * speedY) / gravity;
+        const speedX = (viewW * 0.5) / (vxTypical * apexSec);
+        // 배율은 양쪽 다 조인다 — 아주 작거나 아주 큰 창에서 종이가 한 점에 뭉치거나
+        // 화면 밖으로 순식간에 사라지는 것보다는, 조금 낮게/좁게 뜨는 편이 낫다.
+        const clamp = (v, lo, hi) => Math.min(hi, Math.max(lo, v));
+        const kY = clamp(speedY, 0.8, 2.4);
+        const kX = clamp(speedX, 0.7, 2.2);
+        // initialize particle DOM nodes (they exist but are empty) and start time per particle
+        const particles = pieces.map((p) => ({
+            ...p,
+            vx: p.vx * kX,
+            vy: p.vy * kY,
+            startTime: start + p.delay,
+            ended: false,
+        }));
+        // start positions intentionally off-screen (below and slightly outside horizontally)
+        const originLeft = rect
+            ? { x: rect.left - sideOffset(rect.width), y: rect.top + rect.height + off }
+            : { x: -sideOffset(window.innerWidth), y: window.innerHeight + off };
+        const originRight = rect
+            ? { x: rect.left + rect.width + sideOffset(rect.width), y: rect.top + rect.height + off }
+            : { x: window.innerWidth + sideOffset(window.innerWidth), y: window.innerHeight + off };
+        const step = (now) => {
+            let alive = false;
+            for (const p of particles) {
+                const node = nodesRef.current[p.id];
+                if (!node)
+                    continue;
+                if (!node)
+                    continue;
+                if (now < p.startTime) {
+                    // waiting to start: keep hidden
+                    node.style.display = "none";
+                    continue;
+                }
+                // initialize origin positioning once when particle starts
+                if (!p._inited) {
+                    const ox = p.side === 'left' ? originLeft.x : originRight.x;
+                    const oy = p.side === 'left' ? originLeft.y : originRight.y;
+                    node.style.left = `${ox}px`;
+                    node.style.top = `${oy}px`;
+                    node.style.transform = `translate3d(0px, 0px, 0)`;
+                    node.style.display = "block";
+                    // ensure particle is above overlays
+                    node.style.zIndex = '100000';
+                    // if color is a CSS variable (e.g. var(--color-main)), resolve it now
+                    try {
+                        if (typeof window !== 'undefined' && typeof p.color === 'string' && p.color.startsWith('var(')) {
+                            const varName = p.color.slice(4, -1).trim();
+                            const resolved = getComputedStyle(document.documentElement).getPropertyValue(varName).trim();
+                            if (resolved)
+                                node.style.background = resolved;
+                            else
+                                node.style.background = '#FF0060';
+                        }
+                    }
+                    catch (e) {
+                        // ignore
+                    }
+                    p._inited = true;
+                }
+                const t = (now - p.startTime) / 1000; // seconds since particle start
+                if (t < 0)
+                    continue;
+                const life = p.life / 1000;
+                if (t >= life) {
+                    node.style.opacity = "0";
+                    node.style.display = "none";
+                    p.ended = true;
+                    continue;
+                }
+                alive = true;
+                // physics
+                const ox = p.side === "left" ? originLeft.x : originRight.x;
+                const oy = p.side === "left" ? originLeft.y : originRight.y;
+                const x = ox + p.vx * t;
+                const y = oy + p.vy * t + 0.5 * gravity * t * t;
+                const rotate = (p.angularVel || 0) * t;
+                const dx = x - ox;
+                const dy = y - oy;
+                node.style.transform = `translate3d(${dx}px, ${dy}px, 0) rotate(${rotate}deg)`;
+                node.style.opacity = `${Math.max(0, 1 - t / life)}`;
+            }
+            if (alive) {
+                rafRef.current = requestAnimationFrame(step);
+            }
+            else {
+                // all done
+                onCompleteRef.current?.();
+            }
+        };
+        rafRef.current = requestAnimationFrame(step);
+        // fallback: if portal didn't mount nodes, create them directly
+        const fallbackTimerId = setTimeout(() => {
+            try {
+                const els = mountElRef.current ? mountElRef.current.querySelectorAll('.confetti') : document.querySelectorAll('.confetti');
+                // no debug logging in production
+                // if no elements were rendered (portal didn't append for some reason), create them directly
+                if (els.length === 0) {
+                    if (document.querySelector('.party-container')) {
+                        // already present, skip
+                    }
+                    else {
+                        // create fallback confetti DOM
+                        const fallbackContainer = document.createElement('div');
+                        fallbackContainer.className = 'party-container';
+                        fallbackContainer.style.position = 'fixed';
+                        fallbackContainer.style.inset = '0';
+                        fallbackContainer.style.pointerEvents = 'none';
+                        fallbackContainer.style.overflow = 'visible';
+                        // append to body to avoid stacking context issues
+                        fallbackContainer.style.zIndex = '2147483647';
+                        for (const p of pieces) {
+                            const s = document.createElement('span');
+                            s.className = `confetti confetti--${p.side}`;
+                            s.setAttribute('aria-hidden', 'true');
+                            s.style.display = 'none';
+                            s.style.position = 'fixed';
+                            s.style.left = '0px';
+                            s.style.top = '0px';
+                            s.style.width = `${p.size}px`;
+                            s.style.height = `${Math.max(4, p.size * 0.6)}px`;
+                            // resolve CSS var() color if present
+                            let bg = p.color;
+                            try {
+                                if (typeof bg === 'string' && bg.startsWith('var(')) {
+                                    const varName = bg.slice(4, -1).trim();
+                                    const resolved = getComputedStyle(document.documentElement).getPropertyValue(varName).trim();
+                                    if (resolved)
+                                        bg = resolved;
+                                }
+                            }
+                            catch (e) { }
+                            s.style.background = bg;
+                            s.style.borderRadius = p.borderRadius;
+                            s.style.transform = 'translate3d(0,0,0)';
+                            s.style.opacity = '0';
+                            fallbackContainer.appendChild(s);
+                            nodesRef.current[p.id] = s;
+                        }
+                        (document.body || mountElRef.current).appendChild(fallbackContainer);
+                        fallbackContainerRef.current = fallbackContainer;
+                    }
+                }
+            }
+            catch (e) {
+                // ignore debug errors
+            }
+        }, 300);
+        return () => {
+            if (rafRef.current)
+                cancelAnimationFrame(rafRef.current);
+            clearTimeout(fallbackTimerId);
+            if (fallbackContainerRef.current) {
+                try {
+                    fallbackContainerRef.current.remove();
+                }
+                catch (e) { /* noop */ }
+                fallbackContainerRef.current = null;
+            }
+        };
+    }, [active, duration, trigger, pieces]);
+    if (!active)
+        return null;
+    const node = (_jsx("div", { className: "party-container", ref: containerRef, children: pieces.map((p) => (_jsx("span", { "aria-hidden": true, ref: (el) => { nodesRef.current[p.id] = el; }, className: `confetti confetti--${p.side}`, style: {
+                width: `${p.size}px`,
+                height: `${Math.max(4, p.size * 0.6)}px`,
+                background: p.color,
+                borderRadius: p.borderRadius,
+            } }, `${p.id}-${trigger}`))) }));
+    if (typeof document !== "undefined") {
+        // createPortal의 target은 렌더링 시점에 동기적으로 결정되어야 하므로 ref 읽기를 effect로 옮길 수 없다
+        // eslint-disable-next-line react-hooks/refs
+        return createPortal(node, mountElRef.current || document.body);
+    }
+    return node;
+}

package/dist/packages/core/src/components/Effect/EffectPartyPopperHost.d.ts

@@ -0,0 +1,5 @@
+/** @public */
+export default function EffectPartyPopperHost({ trigger, active }: {
+    trigger?: number;
+    active?: boolean;
+}): import("react").JSX.Element;

package/dist/packages/core/src/components/Effect/EffectPartyPopperHost.js

@@ -0,0 +1,13 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useRef } from "react";
+import EffectPartyPopper from "./EffectPartyPopper";
+/** @public */
+export default function EffectPartyPopperHost({ trigger = 0, active = false }) {
+    const ref = useRef(0);
+    useEffect(() => {
+        ref.current = trigger;
+    }, [trigger]);
+    // The host orchestrates triggers and mounts the popper; it keeps minimal state
+    return _jsx(EffectPartyPopper, { active: active, trigger: trigger });
+}

package/dist/packages/core/src/components/EmptyState.css

@@ -0,0 +1,23 @@
+.empty-state {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  padding: var(--spacing-page) var(--spacing-xl);
+  gap: 10px;
+  text-align: center;
+  border: 1px solid var(--color-whiteLine);
+  border-radius: var(--radius-m);
+}
+.empty-state__emoji { font-size: 40px; line-height: 1; }
+.empty-state__icon { width: 40px; height: 40px; color: var(--color-lightGray); }
+.empty-state__title { color: var(--color-lightGray); margin: 0; }
+.empty-state__message { color: var(--color-gray); margin: 0; }
+.empty-state__hint { color: var(--color-lightGray); margin: 0; }
+.empty-state__action { margin-top: var(--spacing-xs); min-width: 120px; }
+
+/* 표의 빈 행처럼 좁은 자리 — 페이지 여백 대신 컨텐츠 여백을 쓴다 */
+.empty-state--compact {
+  padding: var(--spacing-page) var(--spacing-m);
+  padding-block: 56px;
+}

package/dist/packages/core/src/components/EmptyState.d.ts

@@ -0,0 +1,19 @@
+import './EmptyState.css';
+/** @public */
+export interface EmptyStateProps {
+    icon?: string;
+    emoji?: string;
+    title?: string;
+    message?: string;
+    /** 메시지 아래 보조 안내(선택). message와 별도 문단으로 렌더 — 문자열 접합 오용 방지. */
+    hint?: string;
+    action?: {
+        label: string;
+        icon?: string;
+        onClick: () => void;
+    };
+    /** 표 안의 빈 행처럼 좁은 자리에 넣을 때 위아래 여백을 줄인다. */
+    compact?: boolean;
+    className?: string;
+}
+export default function EmptyState({ icon, emoji, title, message, hint, action, compact, className }: EmptyStateProps): import("react").JSX.Element;

package/dist/packages/core/src/components/EmptyState.js

@@ -0,0 +1,7 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from '../utils/cx';
+import './EmptyState.css';
+import Icon from './Icon';
+export default function EmptyState({ icon, emoji, title, message, hint, action, compact, className }) {
+    return (_jsxs("div", { className: cx('empty-state', compact && 'empty-state--compact', className), children: [emoji && _jsx("span", { className: "empty-state__emoji", children: emoji }), icon && _jsx(Icon, { icon: icon, className: "empty-state__icon" }), title && _jsx("p", { className: "empty-state__title body-2", children: title }), message && _jsx("p", { className: "empty-state__message body-3", children: message }), hint && _jsx("p", { className: "empty-state__hint caption-1", children: hint }), action && (_jsxs("button", { className: "empty-state__action button button40 button40--bar button--variant-main button--align-center button--shape-rounded", onClick: action.onClick, children: [action.icon && _jsx(Icon, { icon: action.icon, className: "button__icon" }), _jsx("span", { className: "button__label button-1", children: action.label })] }))] }));
+}

package/dist/packages/core/src/components/ErrorState.css

@@ -0,0 +1,2 @@
+/* ErrorState — EmptyState 레이아웃(empty-state) 재사용, 에러 톤만 오버라이드 */
+.error-state__icon { color: var(--color-error); }

package/dist/packages/core/src/components/ErrorState.d.ts

@@ -0,0 +1,18 @@
+import './EmptyState.css';
+import './ErrorState.css';
+/** @public
+ *  로드/조회 실패를 빈상태와 구분해 표시하는 공용 컴포넌트. '다시 시도'(retry) 액션을 표준으로 제공한다.
+ *  EmptyState와 레이아웃을 공유(empty-state 클래스 재사용)하되 에러 톤(아이콘 색)만 달리한다. */
+export interface ErrorStateProps {
+    /** 에러 메시지(미지정 시 공용 기본 문구). */
+    message?: string;
+    /** 보조 안내(선택). */
+    hint?: string;
+    icon?: string;
+    /** 다시 시도 콜백 — 지정 시 '다시 시도' 버튼 노출. */
+    onRetry?: () => void;
+    /** 재시도 버튼 라벨(미지정 시 공용 기본). */
+    retryLabel?: string;
+    className?: string;
+}
+export default function ErrorState({ message, hint, icon, onRetry, retryLabel, className }: ErrorStateProps): import("react").JSX.Element;

package/dist/packages/core/src/components/ErrorState.js

@@ -0,0 +1,11 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useTranslation } from 'react-i18next';
+import { cx } from '../utils/cx';
+import './EmptyState.css';
+import './ErrorState.css';
+import Icon from './Icon';
+export default function ErrorState({ message, hint, icon = 'triangle-alert', onRetry, retryLabel, className }) {
+    const { t } = useTranslation();
+    return (_jsxs("div", { className: cx('empty-state', 'error-state', className), role: "alert", children: [_jsx(Icon, { icon: icon, className: "empty-state__icon error-state__icon" }), _jsx("p", { className: "empty-state__message body-3", children: message ?? t('common.errorState.message', { defaultValue: '불러오지 못했습니다.' }) }), hint && _jsx("p", { className: "empty-state__hint caption-1", children: hint }), onRetry && (_jsxs("button", { className: "empty-state__action button button40 button40--bar button--variant-main button--align-center button--shape-rounded", onClick: onRetry, children: [_jsx(Icon, { icon: "rotate-cw", className: "button__icon" }), _jsx("span", { className: "button__label button-1", children: retryLabel ?? t('common.errorState.retry', { defaultValue: '다시 시도' }) })] }))] }));
+}

package/dist/packages/core/src/components/FileUpload.css

@@ -0,0 +1,114 @@
+.file-upload {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-s);
+}
+
+.file-upload__dropzone {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: var(--spacing-xs);
+  padding: var(--spacing-xl);
+  border: 1px dashed var(--color-whiteLine);
+  border-radius: var(--radius-card);
+  background: var(--color-deepWhite);
+  cursor: pointer;
+  transition: border-color 0.15s, background 0.15s;
+}
+
+.file-upload__dropzone:hover:not(.file-upload__dropzone--disabled) {
+  border-color: var(--color-main);
+}
+
+.file-upload__dropzone:focus-visible {
+  outline: 2px solid var(--color-main);
+  outline-offset: 2px;
+}
+
+.file-upload__dropzone--dragging {
+  border-color: var(--color-main);
+  background: var(--color-main-a10);
+}
+
+.file-upload__dropzone--disabled {
+  cursor: not-allowed;
+  opacity: 0.5;
+}
+
+.file-upload__icon {
+  color: var(--color-gray);
+}
+
+.file-upload__prompt {
+  color: var(--color-gray);
+  text-align: center;
+}
+
+.file-upload__browse-button {
+  appearance: none;
+  border: 1px solid var(--color-whiteLine);
+  border-radius: var(--radius-sm);
+  background: var(--color-pureWhite);
+  color: var(--color-main);
+  padding: var(--spacing-xs) var(--spacing-m);
+  cursor: pointer;
+}
+
+.file-upload__browse-button:disabled {
+  cursor: not-allowed;
+  color: var(--color-disabled);
+}
+
+.file-upload__input {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  opacity: 0;
+  overflow: hidden;
+  pointer-events: none;
+}
+
+.file-upload__list {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-xs);
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.file-upload__list-item {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--spacing-s);
+  padding: var(--spacing-xs) var(--spacing-s);
+  border-radius: var(--radius-sm);
+  background: var(--color-deepWhite);
+}
+
+.file-upload__file-name {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  color: var(--color-darkGray);
+}
+
+.file-upload__remove-button {
+  appearance: none;
+  border: none;
+  background: transparent;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--color-gray);
+  cursor: pointer;
+  flex-shrink: 0;
+}
+
+.file-upload__remove-button:hover {
+  color: var(--color-error);
+}

package/dist/packages/core/src/components/FileUpload.d.ts

@@ -0,0 +1,25 @@
+import './FileUpload.css';
+/** @public */
+export interface FileUploadProps {
+    /** 파일 선택(드래그·드롭·클릭) 시 호출. 선택된 File[]을 그대로 전달 — 업로드/네트워크는 호출부 책임 */
+    onFilesSelected?: (files: File[]) => void;
+    /** input accept 속성 (예: "image/*", ".pdf,.docx") */
+    accept?: string;
+    multiple?: boolean;
+    disabled?: boolean;
+    /** 선택된 파일 목록을 컴포넌트 내부에서 표시할지 여부. 기본 true */
+    showFileList?: boolean;
+    /** 표시 중인 파일 목록 (제어형). 미지정 시 내부 상태로 관리 */
+    files?: File[];
+    /** 목록에서 제거 버튼 클릭 시 호출 */
+    onRemove?: (index: number) => void;
+    className?: string;
+}
+/**
+ * 드래그앤드롭 + 클릭 업로드 UI 셸. 드래그 상태, 네이티브 파일 선택창 오픈,
+ * accept/multiple 속성, 선택 파일 목록(제거 버튼 포함) 표시만 담당하며
+ * 실제 업로드/네트워크 로직은 포함하지 않는다 — 선택된 File[]을
+ * onFilesSelected로 넘겨받아 호출부(app)에서 업로드를 처리한다.
+ * @public
+ */
+export default function FileUpload({ onFilesSelected, accept, multiple, disabled, showFileList, files: controlledFiles, onRemove, className, }: FileUploadProps): import("react").JSX.Element;

package/dist/packages/core/src/components/FileUpload.js

@@ -0,0 +1,111 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from '../utils/cx';
+import { useRef, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import Icon from './Icon';
+import './FileUpload.css';
+/** accept 패턴(콤마 구분, 예: "image/*, .pdf") 중 하나라도 file과 일치하면 true. accept 미지정 시 항상 true */
+function matchesAccept(file, accept) {
+    if (!accept)
+        return true;
+    const patterns = accept.split(',').map(p => p.trim()).filter(Boolean);
+    if (patterns.length === 0)
+        return true;
+    const name = file.name.toLowerCase();
+    const type = file.type.toLowerCase();
+    return patterns.some(pattern => {
+        const p = pattern.toLowerCase();
+        if (p.startsWith('.'))
+            return name.endsWith(p);
+        if (p.endsWith('/*'))
+            return type.startsWith(p.slice(0, -1));
+        return type === p;
+    });
+}
+/**
+ * 드래그앤드롭 + 클릭 업로드 UI 셸. 드래그 상태, 네이티브 파일 선택창 오픈,
+ * accept/multiple 속성, 선택 파일 목록(제거 버튼 포함) 표시만 담당하며
+ * 실제 업로드/네트워크 로직은 포함하지 않는다 — 선택된 File[]을
+ * onFilesSelected로 넘겨받아 호출부(app)에서 업로드를 처리한다.
+ * @public
+ */
+export default function FileUpload({ onFilesSelected, accept, multiple = false, disabled = false, showFileList = true, files: controlledFiles, onRemove, className = '', }) {
+    const { t } = useTranslation();
+    const inputRef = useRef(null);
+    const [isDragging, setIsDragging] = useState(false);
+    const [internalFiles, setInternalFiles] = useState([]);
+    const files = controlledFiles ?? internalFiles;
+    const applyFiles = (list) => {
+        if (!list || list.length === 0)
+            return;
+        // 네이티브 <input accept>는 클릭 경로의 파일 선택창만 필터링한다 — 드래그앤드롭은
+        // 브라우저가 accept를 전혀 검사하지 않으므로, accept를 우회해 임의 파일을 드롭하면
+        // 그대로 통과한다. 두 경로 결과가 같도록 여기서 accept 패턴을 재적용해 걸러낸다.
+        const matched = Array.from(list).filter(file => matchesAccept(file, accept));
+        if (matched.length === 0)
+            return;
+        // multiple도 같은 이유로 여기서 다시 적용해야 한다 — 브라우저는 드래그앤드롭에
+        // multiple을 검사하지 않으므로, 단일 선택 UI에 여러 개를 드롭하면 그대로 다 들어왔다
+        // (실측: multiple 미지정인데 2개 드롭 → 2개 통과). 첫 파일만 취한다.
+        const picked = multiple ? matched : matched.slice(0, 1);
+        // multiple일 때 매번 전체를 교체하면, 드래그/선택을 두 번에 나눠 하면(예: 파일 A 선택 후
+        // 파일 B를 추가로 드래그) 목록에 B만 남고 A가 사라진다 — "다중 선택"의 기대와 어긋난다.
+        // 비제어(내부 상태) 모드에서는 기존 선택에 이어붙이고, onFilesSelected도 항상 최신 전체
+        // 목록을 넘겨 내부 표시 목록과 호출부가 보는 값이 어긋나지 않게 한다.
+        if (controlledFiles === undefined) {
+            /* 알림은 업데이터 **밖에서** 부른다. 안에서 부르면 개발 모드(StrictMode)에서
+               업데이터가 두 번 불리며 호출부도 두 번 불린다 — 업로드는 호출부 책임이라
+               같은 파일이 두 번 올라간다(실측: 한 번 골랐는데 두 번). */
+            const next = multiple ? [...files, ...picked] : picked;
+            setInternalFiles(next);
+            onFilesSelected?.(next);
+        }
+        else {
+            onFilesSelected?.(picked);
+        }
+    };
+    const handleDragOver = (e) => {
+        e.preventDefault();
+        if (disabled)
+            return;
+        setIsDragging(true);
+    };
+    const handleDragLeave = (e) => {
+        e.preventDefault();
+        setIsDragging(false);
+    };
+    const handleDrop = (e) => {
+        e.preventDefault();
+        setIsDragging(false);
+        if (disabled)
+            return;
+        applyFiles(e.dataTransfer.files);
+    };
+    const handleInputChange = (e) => {
+        applyFiles(e.target.files);
+        e.target.value = '';
+    };
+    const handleBrowseClick = () => {
+        if (disabled)
+            return;
+        inputRef.current?.click();
+    };
+    const handleRemove = (index) => {
+        if (onRemove) {
+            onRemove(index);
+            return;
+        }
+        if (controlledFiles === undefined) {
+            /* 뺐다는 것도 알린다. 목록만 줄이고 가만히 있으면 **호출부 손에는 그 파일이
+               그대로 남아** 사용자가 뺀 것이 올라간다. */
+            const next = files.filter((_, i) => i !== index);
+            setInternalFiles(next);
+            onFilesSelected?.(next);
+        }
+    };
+    return (_jsxs("div", { className: `file-upload ${className}`.trim(), children: [_jsxs("div", { className: cx('file-upload__dropzone', isDragging && 'file-upload__dropzone--dragging', disabled && 'file-upload__dropzone--disabled'), role: "button", tabIndex: disabled ? -1 : 0, "aria-disabled": disabled, onClick: handleBrowseClick, onKeyDown: e => { if (e.key === 'Enter' || e.key === ' ') {
+                    e.preventDefault();
+                    handleBrowseClick();
+                } }, onDragOver: handleDragOver, onDragLeave: handleDragLeave, onDrop: handleDrop, children: [_jsx(Icon, { icon: "upload", size: 24, className: "file-upload__icon" }), _jsx("span", { className: "file-upload__prompt body-2", children: t('fileUpload.dragPrompt', '파일을 이곳에 드래그하여 업로드') }), _jsx("button", { type: "button", className: "file-upload__browse-button body-3", disabled: disabled, onClick: e => { e.stopPropagation(); handleBrowseClick(); }, children: t('fileUpload.browseButton', '파일 선택') }), _jsx("input", { ref: inputRef, type: "file", className: "file-upload__input", accept: accept, multiple: multiple, disabled: disabled, onChange: handleInputChange, tabIndex: -1 })] }), showFileList && files.length > 0 && (_jsx("ul", { className: "file-upload__list", children: files.map((file, index) => (_jsxs("li", { className: "file-upload__list-item body-3", children: [_jsx("span", { className: "file-upload__file-name body-3", children: file.name }), _jsx("button", { type: "button", className: "file-upload__remove-button", "aria-label": t('fileUpload.removeAriaLabel', { name: file.name }), onClick: () => handleRemove(index), children: _jsx(Icon, { icon: "x", size: 14 }) })] }, `${file.name}-${index}`))) }))] }));
+}