@ihabdevteam/core 0.128.0 → 0.131.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/BottomNav.css

@@ -38,6 +38,21 @@
   overflow: hidden;
 }
 
+/* 단추 한 칸 — 단추와 같은 52px 이라 넘침 계산이 그대로다. 배지(.circle-badge--top-right)의 기준.
+   배지는 Badge 기본 코너(-6px)가 아니라 칸 안쪽 모서리(0)에 둔다 — .bottom-nav__items 가
+   overflow: hidden 이라 바깥으로 나간 6px 가 잘린다(넘침 계산을 위해 그 hidden 은 둬야 한다). */
+.bottom-nav__slot {
+  position: relative;
+  display: flex;
+  flex-shrink: 0;
+  width: 52px;
+  height: 52px;
+}
+.bottom-nav__slot .circle-badge--top-right {
+  top: 0;
+  right: 0;
+}
+
 .bottom-nav__right {
   display: flex;
   align-items: center;

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

@@ -6,6 +6,12 @@ export type NavItem = {
     label?: string;
     icon?: string;
     state?: string;
+    /**
+     * 단추 우상단 원형 숫자 배지(SideNav 항목 배지와 같은 모양). 0/undefined 면 숨기고, 99 에서 자른다.
+     * 배지는 낭독기에서 숨기고 개수는 단추 이름에 붙인다. 넘쳐 "…" 메뉴로 가면 메뉴 항목의 배지가 되고,
+     * "…" 단추에는 넘친 항목 개수의 합이 선다.
+     */
+    badgeCount?: number;
 };
 /**
  * 항상 "더보기(…)" 메뉴에만 노출되는 유틸 항목(알림·설정·계정 등).

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

@@ -4,6 +4,7 @@ import { useCallback, useId, useMemo, useState, useRef, useEffect } from 'react'
 import { createPortal } from 'react-dom';
 import './BottomNav.css';
 import Button from './Button';
+import Badge from './Badge';
 import MenuTooltip from './Tooltip/MenuTooltip';
 // .tooltip-content(메뉴 표면)를 직접 쓰므로 정의 파일을 명시적으로 가져온다.
 // Tooltip.tsx만 이 CSS를 import하는데 BottomNav는 그 컴포넌트를 거치지 않아,
@@ -13,6 +14,8 @@ import { useAnchoredMenu } from '../hooks/useAnchoredMenu';
 import { useTranslation } from 'react-i18next';
 const BTN_SIZE = 52;
 const BTN_GAP = 10;
+/** 배지 숫자 — SideNav·MenuTooltip 과 같이 99 에서 자른다. 0 이하·없음은 0. */
+const badgeOf = (n) => (n && n > 0 ? n : 0);
 /** @public */
 export default function BottomNav({ items = [], activeKey, onChange, appMode, onAppModeChange, moreItems = [], }) {
     const { t } = useTranslation();
@@ -59,6 +62,8 @@ export default function BottomNav({ items = [], activeKey, onChange, appMode, on
         onScroll: 'ignore',
         onResize: 'ignore',
     });
+    /* 단추 이름에 개수를 붙인다 — 배지는 aria-hidden 이라 개수는 이름으로만 전해진다. */
+    const nameWithCount = useCallback((label, count) => count > 0 ? t('nav.badgeLabel', { label, count, defaultValue: '{{label}}, {{count}}개' }) : label, [t]);
     const handleModeChange = useCallback(() => onAppModeChange?.(nextMode), [onAppModeChange, nextMode]);
     // 넘친 nav 항목 또는 유틸 항목이 현재 활성 상태면 … 버튼에 그 아이콘/선택표시를 반영
     const activeMore = useMemo(() => hiddenItems.find(it => it.key === activeKey) ?? moreItems.find(it => it.selected || (it.key && it.key === activeKey)), [hiddenItems, activeKey, moreItems]);
@@ -68,6 +73,7 @@ export default function BottomNav({ items = [], activeKey, onChange, appMode, on
                 ...hiddenItems.map(it => ({
                     label: it.label,
                     icon: it.icon,
+                    badgeCount: it.badgeCount,
                     selected: it.key === activeKey,
                     closeOnSelect: true,
                     onClick: () => {
@@ -89,5 +95,10 @@ export default function BottomNav({ items = [], activeKey, onChange, appMode, on
                 })),
             ]
         }], [hiddenItems, moreItems, activeKey, onChange, handleCloseMore]);
-    return (_jsxs("nav", { className: "bottom-nav", "aria-label": t('nav.bottomNav', '하단 네비게이션'), children: [onAppModeChange && (_jsxs(_Fragment, { children: [_jsx("div", { className: "bottom-nav__left", children: _jsx(Button, { size: 52, type: "dot", icon: modeIcon, ariaLabel: modeLabel, className: "bottom-nav-item", onClick: handleModeChange }) }), _jsx("div", { className: "bottom-nav__divider", "aria-hidden": "true" })] })), _jsx("div", { className: "bottom-nav__items", ref: itemsRef, children: visibleItems.map((it) => (_jsx(Button, { size: 52, type: "dot", icon: it.icon, ariaLabel: it.label, selected: it.key === activeKey, disabled: it.state === 'disabled', className: "bottom-nav-item", onClick: () => it.key && onChange?.(it.key) }, it.key))) }), showMore && (_jsxs(_Fragment, { children: [_jsx("div", { className: "bottom-nav__divider", "aria-hidden": "true" }), _jsx("div", { className: "bottom-nav__right", children: _jsxs("div", { ref: moreRef, children: [_jsx(Button, { size: 52, type: "dot", icon: activeMore?.icon ?? 'ellipsis', ariaLabel: activeMore?.label ?? t('nav.more', '더보기'), selected: !!activeMore, className: "bottom-nav-item", onClick: handleToggleMore, "aria-expanded": moreOpen, "aria-controls": moreOpen ? moreMenuId : undefined }), moreOpen && createPortal(_jsx("div", { id: moreMenuId, role: "group", "aria-label": t('nav.moreMenu', '더보기 메뉴'), className: "tooltip-content", style: menuStyle, ref: menuRef, children: _jsx(MenuTooltip, { columns: moreColumns, onClose: handleCloseMore }) }), document.body)] }) })] }))] }));
+    // "…" 단추 배지 — 메뉴 안에서만 보이는 개수(넘친 항목 + 유틸)를 닫힌 채로도 알린다.
+    const moreBadge = [...hiddenItems, ...moreItems].reduce((sum, it) => sum + badgeOf(it.badgeCount), 0);
+    return (_jsxs("nav", { className: "bottom-nav", "aria-label": t('nav.bottomNav', '하단 네비게이션'), children: [onAppModeChange && (_jsxs(_Fragment, { children: [_jsx("div", { className: "bottom-nav__left", children: _jsx(Button, { size: 52, type: "dot", icon: modeIcon, ariaLabel: modeLabel, className: "bottom-nav-item", onClick: handleModeChange }) }), _jsx("div", { className: "bottom-nav__divider", "aria-hidden": "true" })] })), _jsx("div", { className: "bottom-nav__items", ref: itemsRef, children: visibleItems.map((it) => {
+                    const count = badgeOf(it.badgeCount);
+                    return (_jsxs("span", { className: "bottom-nav__slot", children: [_jsx(Button, { size: 52, type: "dot", icon: it.icon, ariaLabel: nameWithCount(it.label, count), selected: it.key === activeKey, disabled: it.state === 'disabled', className: "bottom-nav-item", onClick: () => it.key && onChange?.(it.key) }), count > 0 && (_jsx("span", { "aria-hidden": "true", children: _jsx(Badge, { type: "dot", position: "top-right", number: Math.min(count, 99), size: 24 }) }))] }, it.key));
+                }) }), showMore && (_jsxs(_Fragment, { children: [_jsx("div", { className: "bottom-nav__divider", "aria-hidden": "true" }), _jsx("div", { className: "bottom-nav__right", children: _jsxs("div", { ref: moreRef, className: "bottom-nav__slot", children: [_jsx(Button, { size: 52, type: "dot", icon: activeMore?.icon ?? 'ellipsis', ariaLabel: nameWithCount(activeMore?.label ?? t('nav.more', '더보기'), moreBadge), selected: !!activeMore, className: "bottom-nav-item", onClick: handleToggleMore, "aria-expanded": moreOpen, "aria-controls": moreOpen ? moreMenuId : undefined }), moreBadge > 0 && (_jsx("span", { "aria-hidden": "true", children: _jsx(Badge, { type: "dot", position: "top-right", number: Math.min(moreBadge, 99), size: 24 }) })), moreOpen && createPortal(_jsx("div", { id: moreMenuId, role: "group", "aria-label": t('nav.moreMenu', '더보기 메뉴'), className: "tooltip-content", style: menuStyle, ref: menuRef, children: _jsx(MenuTooltip, { columns: moreColumns, onClose: handleCloseMore }) }), document.body)] }) })] }))] }));
 }

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;