@ihabdevteam/core 0.128.0 → 0.130.0

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

@@ -13,8 +13,10 @@ const VALUE_UPDATE_MS = 250;
 // 실제 dB SPL(물리 음압)은 기기·볼륨 캘리브레이션 없이는 알 수 없어, 대신 임의 기준점
 // 대비 상대값임을 라벨(dBFS가 아닌 dB)과 부호로 드러낸다.
 // 부호는 항상 표시(우측 정렬 + 고정폭 박스라 자릿수가 바뀌어도 숫자 끝 위치는 고정된다).
+// 기준점 대비 상대 dB 를 표시 범위로 조이고 반올림한 값 — 글자와 aria-valuenow 가 같은 수를 쓴다.
+const relDbValue = (dbfs, refDb, displayMin, displayMax) => Math.round(Math.min(displayMax, Math.max(displayMin, dbfs - refDb)));
 const formatRelDb = (dbfs, refDb, displayMin, displayMax) => {
-    const rel = Math.round(Math.min(displayMax, Math.max(displayMin, dbfs - refDb)));
+    const rel = relDbValue(dbfs, refDb, displayMin, displayMax);
     const sign = rel < 0 ? '-' : '+';
     return `${sign}${Math.abs(rel)} dB`;
 };
@@ -24,6 +26,7 @@ const formatRelDb = (dbfs, refDb, displayMin, displayMax) => {
  * @public
  */
 export default function AudioMeter({ analyser, audioElement, orientation = 'horizontal', length, label, labelPos, labelAlign = 'right', floorDb = -60, refDb = -35, displayMin = -5, displayMax = 25, className, ariaLabel, }) {
+    const rootRef = useRef(null);
     const fillRef = useRef(null);
     const valueRef = useRef(null);
     const rafRef = useRef(null);
@@ -31,12 +34,24 @@ export default function AudioMeter({ analyser, audioElement, orientation = 'hori
        audioMeter 머리말). resume 뒤 태워지면 그 노드로 다시 돈다. */
     const [routed, setRouted] = useState(null);
     useEffect(() => {
+        /* role="meter" 는 값이 있어야 미터다 — 예전엔 aria-valuenow·min·max 가 없어 낭독기가
+           "미터" 라고만 읽었다. 값은 **글자와 같은 주기(VALUE_UPDATE_MS)** 로만 바꾼다: 매 프레임
+           속성을 바꾸면 낭독기가 쉴 새 없이 값 변화를 잡는다. 리렌더 없이 속성만 고친다(막대와 같은 방식). */
+        const writeValue = (dbfs) => {
+            const text = formatRelDb(dbfs, refDb, displayMin, displayMax);
+            if (valueRef.current)
+                valueRef.current.textContent = text;
+            const root = rootRef.current;
+            if (root) {
+                root.setAttribute('aria-valuenow', String(relDbValue(dbfs, refDb, displayMin, displayMax)));
+                root.setAttribute('aria-valuetext', text);
+            }
+        };
         const node = analyser ?? getElementAnalyser(audioElement) ?? (routed && routed.el === audioElement ? routed.node : null);
         const fill = fillRef.current;
         if (!node || !fill) {
             fill?.style.setProperty('--meter-level', '0');
-            if (valueRef.current)
-                valueRef.current.textContent = formatRelDb(floorDb, refDb, displayMin, displayMax);
+            writeValue(floorDb);
             let cancelled = false;
             if (!analyser && audioElement) {
                 void routeElementAudio(audioElement).then((n) => { if (!cancelled && n)
@@ -66,17 +81,16 @@ export default function AudioMeter({ analyser, audioElement, orientation = 'hori
             const relDb = dbClamped - refDb;
             const fillRatio = Math.min(1, Math.max(0, (relDb - displayMin) / (displayMax - displayMin)));
             fill.style.setProperty('--meter-level', fillRatio.toFixed(3));
-            if (valueRef.current) {
-                dbSum += dbClamped;
-                dbCount += 1;
-                if (now - lastUpdate >= VALUE_UPDATE_MS) {
-                    const windowAvg = dbSum / dbCount;
-                    displayedDb = displayedDb == null ? windowAvg : displayedDb * 0.6 + windowAvg * 0.4;
-                    valueRef.current.textContent = formatRelDb(displayedDb, refDb, displayMin, displayMax);
-                    dbSum = 0;
-                    dbCount = 0;
-                    lastUpdate = now;
-                }
+            // 글자가 없어도(label 생략) aria-valuenow 는 갱신해야 하므로 평균은 늘 낸다
+            dbSum += dbClamped;
+            dbCount += 1;
+            if (now - lastUpdate >= VALUE_UPDATE_MS) {
+                const windowAvg = dbSum / dbCount;
+                displayedDb = displayedDb == null ? windowAvg : displayedDb * 0.6 + windowAvg * 0.4;
+                writeValue(displayedDb);
+                dbSum = 0;
+                dbCount = 0;
+                lastUpdate = now;
             }
             rafRef.current = requestAnimationFrame(tick);
         };
@@ -95,5 +109,5 @@ export default function AudioMeter({ analyser, audioElement, orientation = 'hori
     const track = (_jsx("div", { className: "audio-meter__track", style: trackStyle, children: _jsx("div", { ref: fillRef, className: "audio-meter__fill" }) }));
     // 자리를 지정하지 않으면 방향이 정한다 — 가로 막대 옆(오른쪽), 세로 막대 아래.
     const pos = labelPos ?? (orientation === 'vertical' ? 'bottom' : 'right');
-    return (_jsxs("div", { className: cx('audio-meter', `audio-meter--${orientation}`, label && `audio-meter--label-${pos}`, label && `audio-meter--align-${labelAlign}`, className), role: "meter", "aria-label": ariaLabel, children: [track, label && (_jsx("span", { ref: valueRef, className: "audio-meter__value caption-2", children: formatRelDb(floorDb, refDb, displayMin, displayMax) }))] }));
+    return (_jsxs("div", { ref: rootRef, className: cx('audio-meter', `audio-meter--${orientation}`, label && `audio-meter--label-${pos}`, label && `audio-meter--align-${labelAlign}`, className), role: "meter", "aria-label": ariaLabel, "aria-valuemin": displayMin, "aria-valuemax": displayMax, "aria-valuenow": relDbValue(floorDb, refDb, displayMin, displayMax), "aria-valuetext": formatRelDb(floorDb, refDb, displayMin, displayMax), children: [track, label && (_jsx("span", { ref: valueRef, className: "audio-meter__value caption-2", children: formatRelDb(floorDb, refDb, displayMin, displayMax) }))] }));
 }

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

@@ -22,10 +22,14 @@ function getInitials(name) {
  */
 export default function Avatar({ src, name, size = 'md', shape = 'circle', className = '' }) {
     const { t } = useTranslation();
-    const [imgFailed, setImgFailed] = useState(false);
+    // 실패는 **그 주소에 대해서만** 기억한다. 불리언 하나로 두면 한 번 깨진 뒤 새 src 가 와도
+    // 계속 이니셜로 남았다(목록 줄을 재사용하거나 사진을 바꿔 올린 경우). 렌더 중에 비교하므로
+    // 이펙트로 되돌리는 한 틀 깜빡임도 없다.
+    const [failedSrc, setFailedSrc] = useState(null);
+    const imgFailed = !!src && failedSrc === src;
     const initials = name ? getInitials(name) : '';
     const showImage = !!src && !imgFailed;
     const showInitials = !showImage && !!initials;
     const label = name || t('avatar.ariaLabel', '사용자 아바타');
-    return (_jsxs("span", { className: `avatar avatar--${size} avatar--${shape} ${className}`.trim(), role: "img", "aria-label": label, children: [showImage && (_jsx("img", { className: "avatar__image", src: src, alt: label, onError: () => setImgFailed(true) })), !showImage && showInitials && (_jsx("span", { className: "avatar__initials", "aria-hidden": "true", children: initials })), !showImage && !showInitials && (_jsx(Icon, { icon: "user-round", size: ICON_SIZE[size], className: "avatar__icon" }))] }));
+    return (_jsxs("span", { className: `avatar avatar--${size} avatar--${shape} ${className}`.trim(), role: "img", "aria-label": label, children: [showImage && (_jsx("img", { className: "avatar__image", src: src, alt: label, onError: () => setFailedSrc(src ?? null) })), !showImage && showInitials && (_jsx("span", { className: "avatar__initials", "aria-hidden": "true", children: initials })), !showImage && !showInitials && (_jsx(Icon, { icon: "user-round", size: ICON_SIZE[size], className: "avatar__icon" }))] }));
 }

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

@@ -27,6 +27,10 @@ export interface BadgeProps {
      */
     size?: 'small' | 'medium' | 'large' | BadgeDotSize;
     className?: string;
+    /**
+     * 접근성 이름. dot 은 주지 않으면 모양에 따라 '선택됨'·'제거'·'제외'·'N번째 선택' 으로 짓고,
+     * bar 는 주면 그 이름으로 읽힌다(안 주면 글자 그대로 읽힌다).
+     */
     'aria-label'?: string;
     label?: string;
     children?: ReactNode;
@@ -54,7 +58,7 @@ export interface BadgeProps {
     /** 우측 아이콘 (bar 전용). Lucide 아이콘 이름 또는 ReactNode */
     iconRight?: ReactNode | string;
     /**
-     * 아이콘 종류 (dot 전용)
+     * 아이콘 종류 (dot 전용). `number` 가 없고 이것도 없으면 `check` 로 그린다.
      * - `check`  — 선택/완료 (파란 체크)
      * - `remove` — 제거 (빨간 ×)
      * - `minus`  — 비활성/제외 (회색 —)

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

@@ -1,5 +1,7 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cx } from '../utils/cx';
+import { useTranslation } from 'react-i18next';
 import Icon from './Icon';
 import './Badge.css';
 // ── 내부 아이콘 ────────────────────────────────────────────────────────────
@@ -15,17 +17,26 @@ function MinusIcon() {
 // ── 컴포넌트 ───────────────────────────────────────────────────────────────
 /** @public */
 export default function Badge(props) {
+    const { t } = useTranslation();
     const { type = 'bar', size, className = '', 'aria-label': ariaLabel, } = props;
     // ── dot (원형) ──────────────────────────────────────────────────────────
     if (type === 'dot') {
         const { icon, number, position = 'top-right', onClick, animate = false } = props;
-        const dotVariant = number !== undefined ? 'number' : icon ?? 'check';
+        // icon 을 안 주면 check 다 — 클래스(파란 바탕)·기본 이름('선택됨')이 이미 check 로 가는데
+        // 그리는 쪽만 `icon === 'check'` 을 봐서 **체크 없는 파란 원**이 나왔다. 셋이 같은 값을 보게 한다.
+        const dotIcon = icon ?? 'check';
+        const dotVariant = number !== undefined ? 'number' : dotIcon;
         // dot 크기는 Button과 같은 숫자 스케일 — 문자열이 오면 기본값(32)으로 떨어뜨린다.
         const dotSize = typeof size === 'number' ? size : 32;
         const cls = cx('circle-badge', `circle-badge--${dotVariant}`, `circle-badge--${position}`, `circle-badge--${dotSize}`, animate ? 'circle-badge--animate' : '', onClick ? 'circle-badge--clickable' : '', className);
+        // 기본 이름을 한국어로 박아 두면 영문 화면에서도 낭독기만 한국어로 읽었다 — 사전을 거친다.
         const defaultLabel = number !== undefined
-            ? `${number}번째 선택`
-            : { check: '선택됨', remove: '제거', minus: '제외' }[icon ?? 'check'];
+            ? t('badge.nthSelected', { n: number, defaultValue: '{{n}}번째 선택' })
+            : {
+                check: t('badge.selected', '선택됨'),
+                remove: t('badge.remove', '제거'),
+                minus: t('badge.exclude', '제외'),
+            }[dotIcon];
         return (_jsxs("span", { className: cls, onClick: onClick, 
             /* `<span role="button">` 은 브라우저가 Enter·Space 를 눌림으로 바꿔 주지 않는다.
                tabIndex 만 있으면 키보드 사용자는 **그 자리에 멈추고도 아무것도 못 한다** —
@@ -38,7 +49,7 @@ export default function Badge(props) {
                    내게** 한다 — 그래야 이벤트의 target·currentTarget 도 실제와 같다. */
                 e.preventDefault();
                 e.currentTarget.click();
-            } : undefined, "aria-label": ariaLabel ?? defaultLabel, role: onClick ? 'button' : undefined, tabIndex: onClick ? 0 : undefined, children: [number !== undefined && number, number === undefined && icon === 'check' && _jsx(CheckIcon, {}), number === undefined && icon === 'remove' && _jsx(RemoveIcon, {}), number === undefined && icon === 'minus' && _jsx(MinusIcon, {})] }));
+            } : undefined, "aria-label": ariaLabel ?? defaultLabel, role: onClick ? 'button' : undefined, tabIndex: onClick ? 0 : undefined, children: [number !== undefined && number, number === undefined && dotIcon === 'check' && _jsx(CheckIcon, {}), number === undefined && dotIcon === 'remove' && _jsx(RemoveIcon, {}), number === undefined && dotIcon === 'minus' && _jsx(MinusIcon, {})] }));
     }
     // ── bar (텍스트) ────────────────────────────────────────────────────────
     const { label, children, variant = 'default', fill = 'filled', minWidth, iconLeft, iconRight, color } = props;
@@ -58,5 +69,8 @@ export default function Badge(props) {
             ...(resolvedColor ? { '--badge-color': resolvedColor } : {}),
         }
         : undefined;
-    return (_jsxs("span", { className: cls, style: style, children: [iconLeft && _jsx(Icon, { icon: iconLeft, size: iconSize, className: "badge__icon" }), label ?? children, iconRight && _jsx(Icon, { icon: iconRight, size: iconSize, className: "badge__icon" })] }));
+    return (
+    // aria-label 을 받아 놓고 bar 에서는 버렸다 — dot 과 같이 건넨다. 이름만 두면 역할 없는
+    // span 이라 낭독기가 무시하므로 이름이 있을 때만 role="img" 를 붙인다(안 주면 예전 그대로).
+    _jsxs("span", { className: cls, style: style, "aria-label": ariaLabel, role: ariaLabel ? 'img' : undefined, children: [iconLeft && _jsx(Icon, { icon: iconLeft, size: iconSize, className: "badge__icon" }), label ?? children, iconRight && _jsx(Icon, { icon: iconRight, size: iconSize, className: "badge__icon" })] }));
 }

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

@@ -11,6 +11,7 @@ export interface BulkBarProps {
     count: number;
     actions: BulkAction[];
     onClear: () => void;
+    /** 선택 해제 단추 글자. 기본은 사전의 `bulkBar.clearSelection`('선택 해제') */
     clearLabel?: string;
     /** count > 0 일 때 자동으로 visible */
     visible?: boolean;
@@ -19,4 +20,4 @@ export interface BulkBarProps {
     /** 제공하면 액션 버튼 왼쪽에 "count / max" 뱃지를 표시 */
     max?: number;
 }
-export default function BulkBar({ count, actions, onClear, clearLabel, visible, content, max, }: BulkBarProps): import("react").JSX.Element;
+export default function BulkBar({ count, actions, onClear, clearLabel: clearLabelProp, visible, content, max, }: BulkBarProps): import("react").JSX.Element;

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

@@ -5,9 +5,11 @@ import { useTranslation } from 'react-i18next';
 import './BulkBar.css';
 import Button from './Button';
 import Badge from './Badge';
-export default function BulkBar({ count, actions, onClear, clearLabel = '선택 해제', visible, content, max, }) {
+export default function BulkBar({ count, actions, onClear, clearLabel: clearLabelProp, visible, content, max, }) {
     const { t } = useTranslation();
     const show = visible !== undefined ? visible : count > 0;
+    /* 기본 문구도 사전에서 — 예전에는 '선택 해제' 가 박혀 영어 화면에서도 한국어였다 */
+    const clearLabel = clearLabelProp ?? t('bulkBar.clearSelection', '선택 해제');
     /* 내용이 한 줄이면 액션을 가로로, 두 줄 이상이면 세로로 둔다.
        줄바꿈 여부를 높이 문턱값으로 재면 칩 크기나 글꼴이 바뀔 때마다 틀리므로,
        자식들이 실제로 같은 줄에 있는지(offsetTop)를 본다. */
@@ -36,5 +38,10 @@ export default function BulkBar({ count, actions, onClear, clearLabel = '선택
         obs.observe(el);
         return () => obs.disconnect();
     }, [content, count]);
-    return (_jsxs("div", { className: `bulk-bar ${show ? 'bulk-bar--visible' : ''}`, children: [_jsx("span", { ref: contentRef, className: "bulk-bar__count body-2", children: content ?? _jsx("b", { children: t('common.selectedCount', { count }) }) }), max !== undefined && (_jsx(Badge, { size: "small", fill: "soft", variant: "main", label: `${count} / ${max}` })), _jsxs("div", { className: `bulk-bar__actions${stacked ? ' bulk-bar__actions--stacked' : ''}`, children: [_jsx(Button, { size: 40, label: clearLabel, onClick: onClear }), actions.map((a, i) => (_jsx(Button, { size: 40, variant: a.variant ?? 'default', icon: a.icon, label: a.label, onClick: a.onClick }, i)))] })] }));
+    return (_jsxs("div", { className: `bulk-bar ${show ? 'bulk-bar--visible' : ''}`, 
+        /* 숨은 막대는 CSS 로 투명(opacity 0)할 뿐 DOM 에 그대로 있다 — 예전에는 그 안의
+           단추가 Tab 순서와 낭독기에 남아, 보이지 않는 '선택 해제'·'삭제' 에 포커스가 갔다.
+           inert 로 포커스·낭독기에서 함께 뺀다(보이는 모양은 CSS 그대로). aria-hidden 은
+           inert 를 모르는 오래된 브라우저를 위한 덧댐이다. */
+        inert: !show || undefined, "aria-hidden": show ? undefined : true, children: [_jsx("span", { ref: contentRef, className: "bulk-bar__count body-2", children: content ?? _jsx("b", { children: t('common.selectedCount', { count }) }) }), max !== undefined && (_jsx(Badge, { size: "small", fill: "soft", variant: "main", label: `${count} / ${max}` })), _jsxs("div", { className: `bulk-bar__actions${stacked ? ' bulk-bar__actions--stacked' : ''}`, children: [_jsx(Button, { size: 40, label: clearLabel, onClick: onClear }), actions.map((a, i) => (_jsx(Button, { size: 40, variant: a.variant ?? 'default', icon: a.icon, label: a.label, onClick: a.onClick }, i)))] })] }));
 }

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

@@ -52,7 +52,7 @@ export default function Calendar({ visits = [], onVisitClick, onVisitMove, onDay
         setMonth(m => m + 1); }, [month]);
     const fmtDate = (d) => `${year}-${String(month + 1).padStart(2, '0')}-${String(d).padStart(2, '0')}`;
     const isToday = (d) => today.getFullYear() === year && today.getMonth() === month && today.getDate() === d;
-    return (_jsxs("div", { children: [_jsxs("div", { className: "calendar-nav", children: [_jsx("button", { className: "calendar-nav__button", onClick: prev, "aria-label": t('calendar.prevMonth', '이전 달'), children: _jsx(Icon, { icon: "chevron-left", label: "", className: "", svgClassName: "calendar-nav__button-icon", size: 18 }) }), _jsx("span", { className: "calendar-nav__title h5", children: t('calendar.yearMonth', { year, month: month + 1 }) }), _jsx("button", { className: "calendar-nav__button", onClick: next, "aria-label": t('calendar.nextMonth', '다음 달'), children: _jsx(Icon, { icon: "chevron-right", label: "", className: "", svgClassName: "calendar-nav__button-icon", size: 18 }) }), _jsxs("div", { className: "calendar-nav__legend", children: [_jsx("span", { className: "calendar-nav__legend-dot calendar-nav__legend-dot--main" }), _jsx("span", { className: "caption-1", children: t('calendar.legend.visited', '방문') }), _jsx("span", { className: "calendar-nav__legend-dot calendar-nav__legend-dot--sub" }), _jsx("span", { className: "caption-1", children: t('calendar.legend.scheduled', '예약') }), _jsx("span", { className: "calendar-nav__legend-dot calendar-nav__legend-dot--disabled" }), _jsx("span", { className: "caption-1", children: t('calendar.legend.noVisit', '미방문') })] })] }), _jsxs("div", { className: "calendar-grid", children: [DOW.map(d => _jsx("div", { className: "calendar-day-header body-3", children: d }, d)), cells.map((d, i) => {
+    return (_jsxs("div", { children: [_jsxs("div", { className: "calendar-nav", children: [_jsx("button", { type: "button", className: "calendar-nav__button", onClick: prev, "aria-label": t('calendar.prevMonth', '이전 달'), children: _jsx(Icon, { icon: "chevron-left", label: "", className: "", svgClassName: "calendar-nav__button-icon", size: 18 }) }), _jsx("span", { className: "calendar-nav__title h5", children: t('calendar.yearMonth', { year, month: month + 1 }) }), _jsx("button", { type: "button", className: "calendar-nav__button", onClick: next, "aria-label": t('calendar.nextMonth', '다음 달'), children: _jsx(Icon, { icon: "chevron-right", label: "", className: "", svgClassName: "calendar-nav__button-icon", size: 18 }) }), _jsxs("div", { className: "calendar-nav__legend", children: [_jsx("span", { className: "calendar-nav__legend-dot calendar-nav__legend-dot--main" }), _jsx("span", { className: "caption-1", children: t('calendar.legend.visited', '방문') }), _jsx("span", { className: "calendar-nav__legend-dot calendar-nav__legend-dot--sub" }), _jsx("span", { className: "caption-1", children: t('calendar.legend.scheduled', '예약') }), _jsx("span", { className: "calendar-nav__legend-dot calendar-nav__legend-dot--disabled" }), _jsx("span", { className: "caption-1", children: t('calendar.legend.noVisit', '미방문') })] })] }), _jsxs("div", { className: "calendar-grid", children: [DOW.map(d => _jsx("div", { className: "calendar-day-header body-3", children: d }, d)), cells.map((d, i) => {
                         if (d === null)
                             return _jsx("div", { className: "calendar-cell empty" }, `empty-${i}`);
                         const day = d;

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

@@ -12,6 +12,8 @@ export interface ColorPickerProps {
     /** 스와치 크기 — Button과 동일한 체계 (32 / 40 / 48), radius도 Button rounded와 동일하게 맞춤 */
     size?: ColorPickerSize;
     className?: string;
+    /** 묶음의 이름(예: '글자 색') — 낭독기가 무엇의 색을 고르는지 읽는다 */
+    ariaLabel?: string;
 }
 /** @public */
-export default function ColorPicker({ value, onChange, palette, size, className, }: ColorPickerProps): import("react").JSX.Element;
+export default function ColorPicker({ value, onChange, palette, size, className, ariaLabel, }: ColorPickerProps): import("react").JSX.Element;

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

@@ -14,9 +14,11 @@ const DEFAULT_PALETTE = [
     '#bfc7d1', // disabled
 ];
 /** @public */
-export default function ColorPicker({ value, onChange, palette = DEFAULT_PALETTE, size = 40, className = '', }) {
+export default function ColorPicker({ value, onChange, palette = DEFAULT_PALETTE, size = 40, className = '', ariaLabel, }) {
     const { t } = useTranslation();
-    return (_jsx("div", { className: `color-picker ${className}`.trim(), role: "group", children: palette.map(hex => {
+    return (
+    /* role="group" 은 이름이 없으면 낭독기가 묶음을 알리지 않는다 — 이름을 받는다 */
+    _jsx("div", { className: `color-picker ${className}`.trim(), role: "group", "aria-label": ariaLabel, children: palette.map(hex => {
             const isSelected = value?.toLowerCase() === hex.toLowerCase();
             return (_jsx("button", { type: "button", className: `color-picker__swatch color-picker__swatch--${size}`, style: { backgroundColor: hex }, onClick: () => onChange(hex), "aria-pressed": isSelected, "aria-label": isSelected ? `${hex} ${t('colorPicker.selected', '선택됨')}` : hex, children: isSelected && (_jsx(Icon, { icon: "check", size: CHECK_ICON_SIZE, className: "color-picker__check" })) }, hex));
         }) }));

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

@@ -7,7 +7,8 @@ export interface DatePickerProps {
     min?: string;
     max?: string;
     disabled?: boolean;
+    /** 값이 없을 때 보이는 문구. 기본은 사전의 `datePicker.chooseDate`('날짜 선택') */
     placeholder?: string;
     className?: string;
 }
-export default function DatePicker({ value, onChange, size, min, max, disabled, placeholder, className, }: DatePickerProps): import("react").JSX.Element;
+export default function DatePicker({ value, onChange, size, min, max, disabled, placeholder: placeholderProp, className, }: DatePickerProps): import("react").JSX.Element;

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

@@ -28,7 +28,9 @@ function formatDisplay(iso) {
     const [y, m, d] = iso.split('-');
     return `${y}. ${m}. ${d}.`;
 }
-function buildYMOptions(viewY, min, max) {
+/* 연월 이름은 `연월이름` 으로 받는다 — 예전에는 `${y}년 ${m + 1}월` 로 박혀 있어 영어 화면에서도
+   한국어 연월이 떴다. 부르는 쪽이 사전(`calendar.yearMonth`, Calendar 와 같은 열쇠)을 넘긴다. */
+function buildYMOptions(viewY, 연월이름, min, max) {
     const startY = min ? +min.split('-')[0] : viewY - 10;
     const endY = max ? +max.split('-')[0] : viewY + 10;
     const opts = [];
@@ -39,13 +41,16 @@ function buildYMOptions(viewY, min, max) {
                 continue;
             if (max && ym > max.slice(0, 7))
                 continue;
-            opts.push({ value: ym, label: `${y}년 ${m + 1}월` });
+            opts.push({ value: ym, label: 연월이름(y, m + 1) });
         }
     }
     return opts;
 }
-export default function DatePicker({ value, onChange, size = 48, min, max, disabled, placeholder = '날짜 선택', className, }) {
+export default function DatePicker({ value, onChange, size = 48, min, max, disabled, placeholder: placeholderProp, className, }) {
     const { t } = useTranslation();
+    /* 기본 안내 문구도 사전에서 — 예전에는 '날짜 선택' 이 박혀 있어 영어 화면에서도 한국어였다.
+       달력 판의 이름(`datePicker.chooseDate`)과 같은 말이라 같은 열쇠를 쓴다. */
+    const placeholder = placeholderProp ?? t('datePicker.chooseDate', '날짜 선택');
     /* 요일은 **사전에서** 가져온다. 예전에는 이 파일에 `['일','월',…]` 로 박혀 있어
        영어 화면의 날짜 고르개만 한국어 요일이 떴다 — 같은 저장소의 `Calendar` 는
        진작 `calendar.dow` 를 쓰고 있었고, 사전에는 영어(`Sun`·`Mon`…)도 들어 있었다. */
@@ -200,7 +205,7 @@ export default function DatePicker({ value, onChange, size = 48, min, max, disab
     for (let d = 1; d <= daysInMonth(viewY, viewM); d++)
         cells.push(d);
     const iconSize = size === 64 ? 20 : size === 40 ? 16 : 18;
-    const ymOptions = buildYMOptions(viewY, min, max);
+    const ymOptions = buildYMOptions(viewY, (year, month) => t('calendar.yearMonth', { year, month, defaultValue: '{{year}}년 {{month}}월' }), min, max);
     const ymValue = `${viewY}-${String(viewM + 1).padStart(2, '0')}`;
     const dropdown = open ? createPortal(_jsxs("div", { ref: menuRef, className: "date-picker__dropdown", style: dropdownStyle, role: "dialog", "aria-label": t('datePicker.chooseDate', '날짜 선택'), tabIndex: -1, children: [_jsxs("div", { className: "date-picker__nav", children: [_jsx("button", { type: "button", className: "date-picker__nav-btn", onClick: prevMonth, "aria-label": t('calendar.prevMonth', '이전 달'), children: _jsx(ChevronLeft, { size: 16, strokeWidth: 2 }) }), _jsx(Dropdown, { className: "date-picker__nav-dropdown", ariaLabel: t('datePicker.selectYearMonth', '연월 선택'), options: ymOptions, value: ymValue, onChange: (v) => {
                             const [y, m] = v.split('-');

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

@@ -2,10 +2,19 @@ import "./EffectPartyPopper.css";
 /** @public */
 export default function EffectPartyPopper({ active, count, duration, strength, // multiplier for speed/spread
 onComplete, trigger, }: {
+    /** true 인 동안 그린다. false 면 아무것도 안 그린다. */
     active?: boolean;
+    /** 조각 수. 좌우로 반씩 나눈다. 기본 40. */
     count?: number;
+    /**
+     * 조각 수명의 기준(ms). 값에 비례해 모든 조각이 더 오래 또는 더 짧게 날다 사라진다 — 기본 2000 에서
+     * 조각 하나는 약 1.5~5.5초 난다(조각마다 다르고, strength 가 크면 조금 길다).
+     */
     duration?: number;
+    /** 속도·퍼짐 배율. 기본 1. */
     strength?: number;
+    /** 모든 조각이 사라지면 부른다(움직임 최소화 설정이면 바로 부른다). */
     onComplete?: () => void;
+    /** 값이 바뀌면 다시 터진다. */
     trigger?: number;
 }): import("react").JSX.Element | null;

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

@@ -5,6 +5,27 @@ 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)"];
+// `duration` 의 기준값. 조각 수명은 이 값일 때의 모양(대략 1.2~4초)을 그대로 두고 duration 에
+// 비례해 늘거나 준다 — 기본값을 준 화면은 예전과 똑같이 터진다.
+const BASE_DURATION = 2000;
+/**
+ * CSS 변수 색(`var(--color-main)`)을 **그 조각 원소 자신** 기준으로 푼다.
+ *
+ * 예전에는 `document.documentElement` 에서 읽었다. 그런데 스코프 CSS(styles.css)는 토큰을
+ * `:root` 가 아니라 `.ihabdevteam-core-scope` 에 두므로, 스코프 안에 붙은 폭죽은 `<html>` 에서
+ * 토큰을 못 찾아 늘 폴백색으로 칠해졌다. 원소 자신의 계산된 스타일은 상속된 토큰을 본다.
+ */
+function resolveColor(el, color) {
+    if (!color.startsWith('var('))
+        return color;
+    try {
+        const varName = color.slice(4, -1).trim();
+        return getComputedStyle(el).getPropertyValue(varName).trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
 /** @public */
 export default function EffectPartyPopper({ active = false, count = 40, duration = 2000, strength = 1, // multiplier for speed/spread
 onComplete, trigger = 0, }) {
@@ -127,8 +148,11 @@ onComplete, trigger = 0, }) {
         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
+        // duration 을 받아 놓고 아무 데도 안 썼다 — 수명에 비례로 건다(기본값이면 배율 1).
+        const lifeScale = duration > 0 ? duration / BASE_DURATION : 1;
         const particles = pieces.map((p) => ({
             ...p,
+            life: p.life * lifeScale,
             vx: p.vx * kX,
             vy: p.vy * kY,
             startTime: start + p.delay,
@@ -164,19 +188,9 @@ onComplete, trigger = 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
+                    // if color is a CSS variable (e.g. var(--color-main)), resolve it now — 조각 원소 기준으로
+                    if (typeof p.color === 'string' && p.color.startsWith('var(')) {
+                        node.style.background = resolveColor(node, p.color) ?? '#FF0060';
                     }
                     p._inited = true;
                 }
@@ -241,18 +255,9 @@ onComplete, trigger = 0, }) {
                             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;
+                            // 아직 문서에 안 붙은 원소라 여기서는 색을 못 푼다 — var() 그대로 두고,
+                            // 조각이 출발할 때(step 의 첫 틀) 붙은 원소 기준으로 푼다.
+                            s.style.background = p.color;
                             s.style.borderRadius = p.borderRadius;
                             s.style.transform = 'translate3d(0,0,0)';
                             s.style.opacity = '0';

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

@@ -3,5 +3,7 @@ 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 })] }))] }));
+    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 && (
+            // type="button" — 없으면 폼 안에서 누르는 순간 폼이 제출된다
+            _jsxs("button", { type: "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.js

@@ -7,5 +7,7 @@ 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: '다시 시도' }) })] }))] }));
+    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", { 
+                // type="button" — 없으면 폼 안에서 다시 시도를 누르는 순간 폼이 제출된다
+                type: "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/FilterPanel.js

@@ -11,6 +11,7 @@ import Dropdown from './Dropdown';
 export { FILTER_ALL_VALUE } from '../types/filterPanel';
 import { FILTER_ALL_VALUE } from '../types/filterPanel';
 import FilterSectionInfo from './FilterSectionInfo';
+import { devWarnOnce } from '../utils/devWarn';
 /** @public */
 export default function FilterPanel({ title, headerAction, collapsible = false, defaultCollapsed = false, collapsed: controlledCollapsed, onCollapsedChange, footer, sections, selected = {}, onSelect, align, sectionAlign, className, }) {
     // align 우선. 없으면 구 prop(sectionAlign) 매핑, 그것도 없으면 inline 기본.
@@ -36,6 +37,12 @@ export default function FilterPanel({ title, headerAction, collapsible = false,
                             // 바로 터진다 — 호출부 데이터 소스(단어 목록 필터링 등) 결함을 여기서까지 전파시키지
                             // 않도록 렌더 직전에 걸러낸다
                             const items = (section.items ?? []).filter((item) => item != null);
+                            /* "전체" 보기(allOption)는 값 FILTER_ALL_VALUE('전체') 로 알린다. 보기 중에 같은 값 '전체' 가
+                               있으면 그 보기를 눌러도 소비자 판정이 "전체" 로 읽고, segmented·dropdown 에서는 열쇠가 겹친다.
+                               저장된 선택과의 호환 때문에 값은 못 바꾸므로 개발 중에 알린다. */
+                            if (section.allOption && items.some((item) => (typeof item === 'string' ? item : item.value) === FILTER_ALL_VALUE)) {
+                                devWarnOnce(`filter-panel-all-value:${section.label}`, `[FilterPanel] '${section.label}' 절에 allOption 과 값 '${FILTER_ALL_VALUE}' 인 보기가 함께 있다 — 두 선택이 구별되지 않는다. 보기 값을 바꿔라.`);
+                            }
                             /* 보기 버튼 한 개. 칸으로 나뉜 절(section.groups)과 안 나뉜 절이 같은 버튼을
                                그리는데, 한때 이 25줄을 두 벌 적어 두었다. 새 속성을 하나 붙일 때 한쪽만
                                붙는 것이 자연스러운 모양이라 갈릴 수밖에 없다. */

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

@@ -21,8 +21,14 @@ export declare function BrandIdentity({ appMode }: {
 export default function Header({ activeKey, onChange, items, malgwiItems: _malgwiItems, managerItems: _managerItems, unreadCount, onDebug, onNotification, onAccount, onSetting, onHelp, appMode, onAppModeChange }: {
     activeKey?: string | null;
     onChange?: (key?: string) => void;
+    /** 지금 모드의 내비 항목. 데스크톱은 SideNav, 모바일은 BottomNav 가 이 목록을 그린다. */
     items?: SideNavItem[];
+    /**
+     * @deprecated 읽지 않는다 — 지금 모드의 목록을 `items` 로 넘긴다.
+     * 모드 전환 때 부르는 쪽이 `items` 를 바꿔 넣으므로 헤더가 두 목록을 따로 들고 있을 까닭이 없다.
+     */
     malgwiItems?: SideNavItem[];
+    /** @deprecated 읽지 않는다 — 지금 모드의 목록을 `items` 로 넘긴다(`malgwiItems` 와 같다). */
     managerItems?: SideNavItem[];
     unreadCount?: number;
     onDebug?: () => void;

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

@@ -43,6 +43,30 @@ export function BrandIdentity({ appMode }) {
 export default function Header({ activeKey, onChange, items, malgwiItems: _malgwiItems, managerItems: _managerItems, unreadCount, onDebug, onNotification, onAccount, onSetting, onHelp, appMode, onAppModeChange }) {
     const { t } = useTranslation();
     const isMobile = useMediaQuery("(max-width: 767px)");
+    /* **모바일 하단 내비에 SideNav 항목을 옮겨 적는다.** 예전에는 `SideNavItem` 을 `NavItem` 으로
+       캐스팅만 해 넘겨, 두 타입의 이름이 다른 칸이 조용히 버려졌다 — `disabled` 가 `state` 로
+       안 가서 **비활성 항목이 모바일에서 눌렸고**, `href` 항목은 새 창 대신 `onChange(key)` 로
+       갔다. SideNav 가 거르는 구획(section)·빈 항목도 같이 거른다.
+       (`badge` 는 BottomNav 에 받을 자리가 없어 아직 못 옮긴다.) */
+    const bottomItems = useMemo(() => (items ?? [])
+        .filter(it => !it.section && (it.key || it.label))
+        .map(it => ({
+        key: it.key,
+        label: typeof it.label === 'string' ? it.label : undefined,
+        icon: it.icon,
+        state: it.disabled ? 'disabled' : undefined,
+    })), [items]);
+    const handleBottomChange = useCallback((key) => {
+        const it = items?.find(i => i.key === key);
+        if (it?.disabled)
+            return;
+        // SideNav 와 같다 — href 가 있으면 앱 안 이동이 아니라 새 창으로 연다.
+        if (it?.href) {
+            window.open(it.href, '_blank', 'noopener,noreferrer');
+            return;
+        }
+        onChange?.(key);
+    }, [items, onChange]);
     // 모바일 하단 더보기(…) 메뉴에 노출할 유틸(알림·설정·도움말·계정·디버그).
     // 데스크톱 SideNav 푸터와 동일한 아이콘/키를 사용해 활성표시가 일관되게 반영된다.
     const bottomMoreItems = useMemo(() => {
@@ -86,7 +110,7 @@ export default function Header({ activeKey, onChange, items, malgwiItems: _malgw
                 onClick: () => { it.onClick?.(); closeUtilMenu(); },
             })),
         }], [bottomMoreItems, activeKey, closeUtilMenu]);
-    return (_jsxs("aside", { className: `header${appMode === 'manager' ? ' header--manager' : ''}`, children: [_jsxs("div", { className: "header__bi", children: [_jsx(BrandIdentity, { appMode: appMode }), _jsxs("div", { className: "header__menu-button", ref: utilTriggerRef, children: [_jsx(Button, { size: 48, type: "dot", shape: "pill", variant: "default", icon: 'menu', ariaLabel: t('header.menuOpen', '메뉴 열기'), onClick: toggleUtilMenu, "aria-expanded": utilOpen, "aria-controls": utilOpen ? utilMenuId : undefined }), utilOpen && createPortal(_jsx("div", { id: utilMenuId, role: "group", "aria-label": t('header.utilMenu', '유틸리티 메뉴'), className: "tooltip-content", style: utilMenuStyle, ref: utilMenuRef, children: _jsx(MenuTooltip, { columns: utilColumns, onClose: closeUtilMenu }) }), document.body)] })] }), _jsx(SideNav, { items: items, activeKey: activeKey ?? undefined, onChange: onChange, unreadCount: unreadCount, onDebug: onDebug, onNotification: onNotification, onAccount: onAccount, onSetting: onSetting, onHelp: onHelp, appMode: appMode, onAppModeChange: onAppModeChange }), isMobile && _jsx(BottomNav, { items: items, activeKey: activeKey ?? undefined, onChange: onChange, appMode: appMode, onAppModeChange: onAppModeChange })] }));
+    return (_jsxs("aside", { className: `header${appMode === 'manager' ? ' header--manager' : ''}`, children: [_jsxs("div", { className: "header__bi", children: [_jsx(BrandIdentity, { appMode: appMode }), _jsxs("div", { className: "header__menu-button", ref: utilTriggerRef, children: [_jsx(Button, { size: 48, type: "dot", shape: "pill", variant: "default", icon: 'menu', ariaLabel: t('header.menuOpen', '메뉴 열기'), onClick: toggleUtilMenu, "aria-expanded": utilOpen, "aria-controls": utilOpen ? utilMenuId : undefined }), utilOpen && createPortal(_jsx("div", { id: utilMenuId, role: "group", "aria-label": t('header.utilMenu', '유틸리티 메뉴'), className: "tooltip-content", style: utilMenuStyle, ref: utilMenuRef, children: _jsx(MenuTooltip, { columns: utilColumns, onClose: closeUtilMenu }) }), document.body)] })] }), _jsx(SideNav, { items: items, activeKey: activeKey ?? undefined, onChange: onChange, unreadCount: unreadCount, onDebug: onDebug, onNotification: onNotification, onAccount: onAccount, onSetting: onSetting, onHelp: onHelp, appMode: appMode, onAppModeChange: onAppModeChange }), isMobile && _jsx(BottomNav, { items: bottomItems, activeKey: activeKey ?? undefined, onChange: handleBottomChange, appMode: appMode, onAppModeChange: onAppModeChange })] }));
 }
 /**
  * `Header`의 alias입니다. 프로젝트 내 `Header`라는 이름이 이미 사용 중일 때 충돌 없이 임포트할 수 있습니다.

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

@@ -0,0 +1,22 @@
+/* ── Icon 마스크 모드 ────────────────────────────────────────────────
+   `.svg` 경로가 SVG 로 응답하면 Icon 은 `<span class="iconRenderer-icon-mask"
+   style="--icon-url: url(…)">` 를 그린다. 그런데 이 이름에 규칙이 하나도 없어서
+   크기 0 · 마스크 없음 — **아무것도 안 그려졌다.** Button·SideNav 는 제
+   maskClassName 에 같은 규칙을 따로 두어 괜찮았고, 기본 이름으로 쓰는 자리만 비었다.
+
+   새 색은 쓰지 않는다 — 글자색(currentColor)으로 칠해 부모의 color 를 따른다.
+   크기는 `size` prop 이 `--icon-size` 로 넘기고, 없으면 lucide 기본과 같은 20px. */
+.iconRenderer-icon-mask {
+  display: inline-block;
+  width: var(--icon-size, 20px);
+  height: var(--icon-size, 20px);
+  background-color: currentColor;
+  -webkit-mask-image: var(--icon-url);
+  -webkit-mask-repeat: no-repeat;
+  -webkit-mask-position: center;
+  -webkit-mask-size: contain;
+  mask-image: var(--icon-url);
+  mask-repeat: no-repeat;
+  mask-position: center;
+  mask-size: contain;
+}

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

@@ -1,4 +1,5 @@
 import { type ReactNode, type CSSProperties } from 'react';
+import './Icon.css';
 /** @public */
 export interface IconProps {
     /**
@@ -11,8 +12,8 @@ export interface IconProps {
     /**
      * 감싸는 `<span>` 의 클래스. 주면 기본 이름을 **갈아치운다** — 덧붙이지 않는다.
      *
-     * 기본값 `iconRenderer-icon` 을 비롯한 네 `iconRenderer-*` 이름은 **패키지에
-     * 제 규칙이 하나도 없다**(실측: 자기 규칙 0개). 붙잡을 이름일 뿐이고 크기는
+     * 기본값 `iconRenderer-icon` 을 비롯한 `iconRenderer-*` 이름은 마스크(`-mask`)를 빼면
+     * **패키지에 제 규칙이 없다**. 붙잡을 이름일 뿐이고 크기는
      * `size`, 그 밖의 모양은 `wrapperStyle` 이나 소비자 CSS 로 간다. 그래서
      * `className="iconRenderer-icon"` 이라고 적어도 아무 모양도 따라오지 않는다.
      *
@@ -23,7 +24,10 @@ export interface IconProps {
     className?: string;
     /** `<img>` 로 그릴 때의 클래스. 기본 `iconRenderer-icon-image` — 규칙 없음. */
     imgClassName?: string;
-    /** 마스크로 그릴 때의 클래스. 기본 `iconRenderer-icon-mask` — 규칙 없음. */
+    /**
+     * 마스크로 그릴 때의 클래스. 기본 `iconRenderer-icon-mask` — 글자색으로 칠하고 크기는 `size`(없으면 20px).
+     * 주면 기본 이름을 갈아치우므로 마스크 규칙(`mask-image: var(--icon-url)` 등)도 그 클래스가 대야 한다.
+     */
     maskClassName?: string;
     /** 인라인 SVG 로 그릴 때의 클래스. 기본 `iconRenderer-icon-svg` — 규칙 없음. */
     svgClassName?: string;