@ihabdevteam/core 0.141.0 → 0.143.0

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

@@ -8,6 +8,7 @@ import { pushEsc } from "../../hooks/escStack";
 import { lockBodyScroll } from "../../hooks/bodyScrollLock";
 import "./Popup.css";
 import { useFocusTrap, FOCUSABLE_SELECTOR } from '../../hooks/useFocusTrap';
+import { rememberFocusReturn, resolveFocusReturn } from '../../hooks/focusReturn';
 const ANIM_MS = 260;
 // 패널 안에서 Tab 순환 대상으로 삼을 요소들 — disabled/tabindex="-1"은 제외.
 /** @public */
@@ -81,7 +82,8 @@ export default function Popup(props) {
     // 포커스 관리 — 이전까진 팝업이 열려도 포커스가 배경(주로 body)에 남아있어서,
     // 키보드 사용자가 Tab을 눌러도 팝업 밖 배경 요소로 이동해버리고(포커스 트랩 없음),
     // 스크린리더는 열린 다이얼로그를 아예 인지하지 못했다. 열릴 때 패널(또는 첫 포커스
-    // 가능 요소)로 포커스를 옮기고, 닫히면 원래 포커스였던 요소로 되돌린다.
+    // 가능 요소)로 포커스를 옮기고, 닫히면 — 포커스가 아직 이 창 안이거나 body 일 때만 —
+    // 원래 포커스였던 요소로 되돌린다(다른 창으로 옮겨 갔으면 그대로 둔다).
     // 단, 자식이 자체 autoFocus를 쓰는 경우(SaveTablePopup 등)는 이미 그쪽으로 포커스가
     // 가 있을 것이므로(브라우저가 커밋 시점에 처리) 뺏지 않는다.
     useEffect(() => {
@@ -89,6 +91,7 @@ export default function Popup(props) {
             return;
         const previouslyFocused = document.activeElement;
         const panel = panelRef.current;
+        rememberFocusReturn(panel, previouslyFocused);
         if (panel && !panel.contains(document.activeElement)) {
             const first = panel.querySelector(FOCUSABLE_SELECTOR);
             (first ?? panel).focus();
@@ -98,8 +101,9 @@ export default function Popup(props) {
                (미리보기 → 삭제 확인)에서는 닫힘 애니메이션(260ms) 뒤에 여기가 돌 때 포커스가 이미 새 창에 있는데,
                전에는 그것을 뒤 화면의 여는 단추로 빼앗아 Tab 가둠이 풀리고 Enter 가 뒤 화면을 눌렀다. */
             const active = document.activeElement;
+            // 기억한 곳이 앞 창과 함께 사라졌으면(미리보기 → 삭제 확인) 그 창이 돌려줄 곳으로
             if (!active || active === document.body || (panel && panel.contains(active)))
-                previouslyFocused?.focus?.();
+                resolveFocusReturn(previouslyFocused)?.focus?.();
         };
     }, [inline]);
     /* Tab 순환을 패널 안으로 가둔다 — 네 곳에 있던 같은 열두 줄을 훅 한 벌로 모았다.
@@ -130,13 +134,11 @@ export default function Popup(props) {
                 되살리기();
                 return;
             }
-            // 부모가 치울 틈(렌더·커밋)을 준 뒤에도 남아 있으면 되살린다
-            const 남았으면 = () => { setTimeout(되살리기, 120); };
+            /* 약속을 돌려준 콜백만 **끝난 뒤에도 남아 있으면** 되살린다. 동기 콜백(undefined)은 되살리지 않는다 — 부모가 저장을
+               따로 기다렸다 닫는 흔한 꼴(onSave 를 부르고 약속은 안 돌려줌)에서 기다리는 사이 창이 다시 보이고 저장 단추가 다시
+               눌려 두 번 저장됐다. 저장 실패에 창을 되살리고 싶으면 콜백이 그 약속을 돌려주면 된다. */
             if (결과 && typeof 결과.then === 'function') {
-                결과.then(남았으면, 되살리기);
-            }
-            else {
-                남았으면();
+                결과.then(() => { setTimeout(되살리기, 120); }, 되살리기);
             }
         }, ANIM_MS);
     }, [되살리기]);
@@ -185,7 +187,7 @@ export default function Popup(props) {
             e.preventDefault(); }, children: _jsxs("div", { ref: panelRef, className: `popup-panel${size ? ` popup-panel--${size}` : ''}${height != null ? ' popup-panel--has-height' : ''}${fillBody ? ' popup-panel--fill-body' : ''}`, 
             /* 높이는 **CSS 변수로** 넘긴다 — 인라인 height 로 박으면 앱의 미디어 규칙(좁은 화면만 다른 높이)이 못 이겼다.
                max-height(CSS)가 height 보다 이기므로 화면보다 크게 줘도 화면에 맞춰진다 */
-            style: height != null ? { '--popup-height': typeof height === 'number' ? `${height}px` : height } : undefined, tabIndex: -1, role: inline ? undefined : 'dialog', "aria-modal": inline ? undefined : true, "aria-labelledby": !inline && title ? titleId : undefined, "aria-label": !inline && !title && ariaLabel ? ariaLabel : undefined, children: [!useTitle && (headerActions || onClose) ? (_jsxs("div", { className: "popup-close-float", children: [headerActions, onClose && _jsx(Button, { htmlType: "button", size: 40, type: "dot", icon: "x", variant: "transparent-gray", useBorder: false, onClick: closeWithAnimation, disabled: closeDisabled, ariaLabel: t('common.close', '닫기') })] })) : (title || headerActions || onClose) ? (_jsxs("div", { className: `popup-header${subtitle ? ' popup-header--with-subtitle' : ''}`, children: [_jsxs("div", { className: "popup-header-main", children: [_jsx("span", { id: titleId, className: "popup-title popup-title--left h2", children: title }), subtitle && _jsx("span", { className: "popup-subtitle body-3", children: subtitle })] }), _jsxs("div", { className: "popup-header-actions", children: [headerActions, onClose && (_jsx(Button, { htmlType: "button", size: 40, type: "dot", icon: "x", variant: "transparent-gray", useBorder: false, onClick: closeWithAnimation, disabled: closeDisabled, ariaLabel: t('common.close', '닫기') }))] })] })) : null, _jsx("div", { className: "popup-content", ref: contentRef, tabIndex: contentScrollable ? 0 : undefined, children: _jsx("div", { className: "popup-content__inner", children: typeof children === 'function' ? children({ animateThen, closeWithAnimation }) : children }) }), buttons?.length ? (_jsx("div", { className: "popup-footer popup-footer--buttons", children: buttons.map((btn, i) => (_jsx(Button, { htmlType: "button", size: 48, variant: btn.variant ?? 'default', label: btn.label, disabled: btn.disabled, onClick: () => btn.onClick?.({ animateThen, closeWithAnimation }) }, i))) })) : footer ? (_jsx("div", { className: `popup-footer${footerClassName ? ` ${footerClassName}` : ''}`, children: typeof footer === 'function' ? footer({ animateThen, closeWithAnimation }) : footer })) : null] }) }));
+            style: height != null ? { '--popup-height': typeof height === 'number' ? `${height}px` : height } : undefined, tabIndex: -1, role: inline ? undefined : 'dialog', "aria-modal": inline ? undefined : true, "aria-labelledby": !inline && useTitle && title ? titleId : undefined, "aria-label": !inline && !(useTitle && title) ? (ariaLabel ?? (typeof title === 'string' ? title : undefined)) : undefined, children: [!useTitle && (headerActions || onClose) ? (_jsxs("div", { className: "popup-close-float", children: [headerActions, onClose && _jsx(Button, { htmlType: "button", size: 40, type: "dot", icon: "x", variant: "transparent-gray", useBorder: false, onClick: closeWithAnimation, disabled: closeDisabled, ariaLabel: t('common.close', '닫기') })] })) : (title || headerActions || onClose) ? (_jsxs("div", { className: `popup-header${subtitle ? ' popup-header--with-subtitle' : ''}`, children: [_jsxs("div", { className: "popup-header-main", children: [_jsx("span", { id: titleId, className: "popup-title popup-title--left h2", children: title }), subtitle && _jsx("span", { className: "popup-subtitle body-3", children: subtitle })] }), _jsxs("div", { className: "popup-header-actions", children: [headerActions, onClose && (_jsx(Button, { htmlType: "button", size: 40, type: "dot", icon: "x", variant: "transparent-gray", useBorder: false, onClick: closeWithAnimation, disabled: closeDisabled, ariaLabel: t('common.close', '닫기') }))] })] })) : null, _jsx("div", { className: "popup-content", ref: contentRef, tabIndex: contentScrollable ? 0 : undefined, children: _jsx("div", { className: "popup-content__inner", children: typeof children === 'function' ? children({ animateThen, closeWithAnimation }) : children }) }), buttons?.length ? (_jsx("div", { className: "popup-footer popup-footer--buttons", children: buttons.map((btn, i) => (_jsx(Button, { htmlType: "button", size: 48, variant: btn.variant ?? 'default', label: btn.label, disabled: btn.disabled, onClick: () => btn.onClick?.({ animateThen, closeWithAnimation }) }, i))) })) : footer ? (_jsx("div", { className: `popup-footer${footerClassName ? ` ${footerClassName}` : ''}`, children: typeof footer === 'function' ? footer({ animateThen, closeWithAnimation }) : footer })) : null] }) }));
     if (inline || typeof document === 'undefined')
         return el;
     return createPortal(el, document.body);

package/dist/packages/core/src/components/Popup/customerDetailUtils.d.ts

@@ -27,7 +27,7 @@ export declare function visitItemKey(v: {
     minute: string;
 }): string;
 /**
- * 초 → "M분 S초"(또는 "M분"·"S초"). 없거나 0 이하면 '-'.
+ * 초 → "M분 S초"(또는 "M분"·"S초"). 초 단위로 반올림한 뒤 나눈다 — 없거나(숫자가 아님) 반올림해 0 이하(0.5초 미만 포함)면 '-'.
  *
  * 문구는 지금 언어로(`customers.duration.*`, 사전에 없으면 한국어). `durationStr` 를 주면
  * 그 함수가 만든 글을 그대로 쓴다 — `calcAge` 의 `ageStr` 와 같은 결.

package/dist/packages/core/src/components/Popup/customerDetailUtils.js

@@ -71,7 +71,7 @@ export function visitItemKey(v) {
     return `${v.year}-${v.month}-${v.day}T${v.hour}:${v.minute}`;
 }
 /**
- * 초 → "M분 S초"(또는 "M분"·"S초"). 없거나 0 이하면 '-'.
+ * 초 → "M분 S초"(또는 "M분"·"S초"). 초 단위로 반올림한 뒤 나눈다 — 없거나(숫자가 아님) 반올림해 0 이하(0.5초 미만 포함)면 '-'.
  *
  * 문구는 지금 언어로(`customers.duration.*`, 사전에 없으면 한국어). `durationStr` 를 주면
  * 그 함수가 만든 글을 그대로 쓴다 — `calcAge` 의 `ageStr` 와 같은 결.

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

@@ -12,7 +12,9 @@ import './TextField.css';
 const useIsoLayoutEffect = typeof window !== 'undefined' ? useLayoutEffect : useEffect;
 /** @public */
 export default function TextField(props) {
-    const { value, defaultValue, name, inputRef, onChange, label, ariaLabel, required, placeholder, type = 'text', disabled = false, readOnly = false, error, helperText, maxLength, size = 48, variant = 'input', fullWidth = false, newline = false, multiline = false, rows = 3, leftIcon, rightIcon, clearable = false, list, showCount = true, className = '', onFocus, onBlur, onKeyDown, onEnter, inputMode, autoComplete, autoFocus, suggestions, openOnFocus = false, } = props;
+    const { value, defaultValue, name, inputRef, onChange, label, ariaLabel, required, placeholder, type = 'text', disabled = false, readOnly = false, error, helperText, maxLength, size = 48, variant = 'input', fullWidth = false, newline = false, multiline = false, rows = 3, leftIcon, rightIcon, clearable = false, list, showCount = true, className = '', onFocus, onBlur, onKeyDown, onEnter, inputMode, autoComplete, autoFocus, suggestions: suggestionsProp, openOnFocus = false, } = props;
+    // 읽기 전용·꺼진 칸은 후보로 값을 바꾸지 못한다 — 전에는 ↓·Enter·후보 누름으로 onChange 가 나갔다
+    const suggestions = readOnly || disabled ? undefined : suggestionsProp;
     const { t } = useTranslation();
     const uid = useId();
     /* **이름 없는 입력칸은 화면을 못 보는 사람에게 빈칸이다.** placeholder 는 이름이

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

@@ -82,7 +82,7 @@ export default function Tooltip(props) {
                 top = rect.top + rect.height / 2 - h / 2;
             }
         }
-        const m = Number(edgeMargin) || 8;
+        const m = Number.isFinite(Number(edgeMargin)) ? Number(edgeMargin) : 8; // 0 도 값이다(`|| 8` 이 0 을 8 로 바꿨다)
         left = Math.min(Math.max(left, m), vw - w - m);
         top = Math.min(Math.max(top, m), vh - h - m);
         const leftRounded = Math.round(left);
@@ -146,6 +146,12 @@ export default function Tooltip(props) {
                 const t = e.target;
                 if (t && ref.current && ref.current.contains(t))
                     return;
+                // 툴팁에서 body 로 빠진 메뉴·달력(data-tooltip-ignore)을 굴리는 것도 툴팁 안의 일이다 — 열자마자 선택값으로 굴리면 닫혔다
+                try {
+                    if (t && t.closest && t.closest('[data-tooltip-ignore]'))
+                        return;
+                }
+                catch (err) { }
                 startCloseRef.current(true);
                 return;
             }

package/dist/packages/core/src/components/Training/TrainingBlock.js

@@ -7,6 +7,7 @@ import Section from '../Section';
 import './TrainingBlock.css';
 import TrainingBlockButton from './TrainingBlockButton';
 import { useWindowEvent } from '../../hooks/useWindowEvent';
+import { 키보드로눌렀나 } from '../../hooks/inputModality';
 const BTN_COUNT_MAX = 20;
 /** @public */
 export default function TrainingBlock(props) {
@@ -34,7 +35,7 @@ export default function TrainingBlock(props) {
     const 더보기초점Ref = useRef(null);
     function loadMore() {
         const 단추 = document.activeElement;
-        더보기초점Ref.current = 단추 && 단추.closest?.('.training-block__more') ? visible : null;
+        더보기초점Ref.current = 키보드로눌렀나() && 단추 && 단추.closest?.('.training-block__more') ? visible : null;
         setVisible((v) => Math.min(total, v + BTN_COUNT_MAX));
     }
     useEffect(() => {

package/dist/packages/core/src/components/Training/TrainingPagePopup.d.ts

@@ -78,7 +78,7 @@ export type TrainingPagePopupProps = {
      * 판에 실제로 걸린 값은 `NoiseSettingsStore.applied` 로 받는다.
      */
     noiseOverride?: Partial<CoreNoiseSettings> | ((saved: CoreNoiseSettings) => Partial<CoreNoiseSettings>);
-    /** 훈련 결과 팝업 렌더러 — 없으면 결과 팝업을 표시하지 않음 */
+    /** 훈련 결과 팝업 렌더러 — 없으면 기본 결과 팝업(TrainingResultPopup)을 띄운다 */
     renderResultPopup?: (props: {
         score?: number | null;
         results?: unknown[];

package/dist/packages/core/src/components/Training/TrainingPagePopup.js

@@ -5,6 +5,7 @@ import { PAGE_POPUP_CLOSE_MS } from './pagePopupTiming';
 import { useTranslation } from 'react-i18next';
 import { createPortal } from "react-dom";
 import { useFocusTrap, FOCUSABLE_SELECTOR } from '../../hooks/useFocusTrap';
+import { rememberFocusReturn, resolveFocusReturn } from '../../hooks/focusReturn';
 import { pushEsc } from '../../hooks/escStack';
 import Toast from '../Toast';
 import Button from '../Button';
@@ -25,6 +26,7 @@ import useTrainingSessionLog from '../../hooks/useTrainingSessionLog';
 import { logTrainingCompletion } from '../../utils/trainingLogger';
 import { toItemResults } from '../../utils/trainingItemResults';
 import { loadNoiseSettings, saveNoiseSettings, reportAppliedNoiseSettings } from '../../utils/noiseSettingsStore';
+import { 키보드로눌렀나 } from '../../hooks/inputModality';
 // 문장 4종은 각 PagePopup 래퍼에서 useTrainingSessionLog로 이미 기록 → 베이스에서 중복 방지
 const SENTENCE_TIME_LOGGED_TYPES = new Set(['LISTEN_IN_NOISE', 'SHORT_STORY', 'LONG_STORY', 'ORDERING_SENTENCE']);
 // renderResultPopup 미지정 시 기본 결과 팝업 — 모든 훈련 타입 공통 폴백
@@ -239,6 +241,7 @@ function TrainingPagePopupInner(props) {
     useEffect(() => {
         const panel = panelRef.current;
         const previouslyFocused = document.activeElement;
+        rememberFocusReturn(panel, previouslyFocused);
         if (panel) {
             const firstEl = Array.from(panel.querySelectorAll(FOCUSABLE_SELECTOR)).filter(el => !el.closest('[aria-hidden="true"]'))[0];
             if (firstEl) {
@@ -253,7 +256,7 @@ function TrainingPagePopupInner(props) {
             const active = document.activeElement;
             if (!active || active === document.body || (panel && panel.contains(active))) {
                 try {
-                    previouslyFocused?.focus?.();
+                    resolveFocusReturn(previouslyFocused)?.focus?.();
                 }
                 catch (e) { }
             }
@@ -763,6 +766,9 @@ function TrainingPagePopupInner(props) {
         앞쪽Ref.current = effectivePageIndex;
         if (앞 === undefined || 앞 === effectivePageIndex)
             return;
+        // 키보드로 넘겼을 때만 — 마우스로 누른 사람에게 매 문제 '듣기' 초점 안내가 뜨지 않게
+        if (!키보드로눌렀나())
+            return;
         const panel = panelRef.current;
         if (!panel)
             return;

package/dist/packages/core/src/components/Training/TrainingStepAudioPlayer.js

@@ -10,6 +10,7 @@ import { resumeAudioMeter, routeElementAudio, setElementVolume, getElementVolume
 import { useNoisePlayer, effectiveNoiseVolume, effectiveSpeechVolume, noiseRatioOf } from './NoisePlayerContext';
 import { useNoiseFade } from './useNoiseFade';
 import { useTTSPlayback } from './useTTSPlayback';
+import { claimSound, stopSoundIfOwner } from './currentSound';
 import './TrainingStepAudioPlayer.css';
 import WaveForm from './AudioPlayerWaveForm';
 import Toast from '../Toast';
@@ -17,6 +18,7 @@ import Button from '../Button';
 import Icon from '../Icon';
 import InfoTooltip from '../Tooltip/InfoTooltip';
 import { STATUS_MESSAGES } from './trainingStepAudioPlayerTypes';
+import { 키보드로눌렀나 } from '../../hooks/inputModality';
 import { measureAudioDuration, waitForCanPlay } from './audioWaits';
 import { useWaveReady } from './useWaveReady';
 import { useObjectUrls } from './useObjectUrls';
@@ -156,7 +158,7 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
         audioRef,
         playbackStateRef,
     });
-    const { startTTS, stopTTS } = useTTSPlayback({
+    const { startTTS: 합성시작, stopTTS } = useTTSPlayback({
         ttsText,
         playbackRate,
         // TTS 음성 = 문제 소리 = 전체 소리
@@ -172,6 +174,8 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
         onDoneRef,
         handleEndRef,
     });
+    useEffect(() => { stopTTSRef.current = stopTTS; });
+    const startTTS = (text) => { 소리잡기('tts'); 합성시작(text); };
     const requestedSources = Array.isArray(soundSrc)
         ? soundSrc.filter(Boolean)
         : (soundSrc ? [soundSrc] : []);
@@ -191,12 +195,50 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
        오류" 로만 보고 다시 부르면 **정지를 눌렀는데 소리가 다시 났다**. 시작할 때의 의도가 그대로일 때만 다시 시도한다. */
     const 재생의도Ref = useRef(0);
     const 멈춤의도 = () => { 재생의도Ref.current += 1; jumpTokenRef.current += 1; };
+    /* 스피커는 하나(currentSound.ts) — 한 화면의 다른 재생기(문장 듣기·문제 듣기)·낱말 카드·미리 듣기가 울리면 이 재생기는
+       멈춘다. 전에는 낱말 카드만 자물쇠를 잡아, 듣기 단계가 둘인 화면·듣기+카드 단계에서 두 소리가 함께 울렸다.
+       멈춤 단추와 같게 멈춘다(이어 듣기 가능). 함수는 한 벌이어야 자물쇠가 '내 것' 을 알아본다. */
+    const stopTTSRef = useRef(null);
+    const 소리종류Ref = useRef(null);
+    const 소리놓기Ref = useRef(null);
+    const 소리멈춤Ref = useRef(null);
+    if (!소리멈춤Ref.current) {
+        소리멈춤Ref.current = () => {
+            소리놓기Ref.current = null;
+            const a = audioRef.current;
+            if (소리종류Ref.current === 'audio' && a && !a.paused) {
+                재생의도Ref.current += 1;
+                jumpTokenRef.current += 1;
+                try {
+                    a.pause();
+                }
+                catch (e) { }
+                if (mountedRef.current)
+                    setPlaybackState('paused');
+            }
+            else if (소리종류Ref.current === 'tts') {
+                try {
+                    stopTTSRef.current?.();
+                }
+                catch (e) { }
+            }
+        };
+    }
+    const 소리잡기 = (종류) => {
+        소리종류Ref.current = 종류;
+        소리놓기Ref.current = claimSound(소리멈춤Ref.current);
+    };
+    // 멈춤·정지·완료 뒤에는 자리를 비운다 — 남이 울릴 때 끝난 재생기의 상태를 건드리지 않게
+    const 소리놓기 = () => { 소리놓기Ref.current?.(); 소리놓기Ref.current = null; };
+    useEffect(() => () => { if (소리멈춤Ref.current)
+        stopSoundIfOwner(소리멈춤Ref.current); }, []);
     const tryPlayWithRetry = useCallback(async (a, attempts = 3, delayMs = 50) => {
         const 의도 = 재생의도Ref.current;
         for (let i = 0; i < attempts; i++) {
             if (!mountedRef.current || 의도 !== 재생의도Ref.current)
                 return false;
             try {
+                소리잡기('audio');
                 await a.play();
                 return true;
             }
@@ -730,6 +772,7 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
                 try {
                     if (synth && synth.paused) {
                         try {
+                            소리잡기('tts');
                             synth.resume();
                             setPlaybackState('playing');
                         }
@@ -846,6 +889,7 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
     const handleStop = () => {
         // 기다리던 트랙 이동·재시도가 정지 뒤에 소리를 내지 않게
         멈춤의도();
+        소리놓기();
         if (ttsMode) {
             stopTTS();
             return;
@@ -948,6 +992,7 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
         const outDelay = 340;
         markCompletedByEnd(true);
         멈춤의도();
+        소리놓기();
         try {
             setProgress(1);
         }
@@ -1092,7 +1137,12 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
     const fillPausedFlag = playbackState === "paused";
     const fillLeftPercent = Math.max(0, Math.min(100, (progress || 0) * 100));
     const fillClass = cx('audio-player__fill', fillVisibleFlag ? 'is-visible' : '', fillExpandedFlag ? 'is-expanded' : '', fillPausedFlag ? 'is-paused' : '', isFillOutAnimating ? 'is-out' : '');
-    return (_jsxs("div", { className: `audio-player ${isDisabled ? 'is-disabled' : ''}${className ? ` ${className}` : ''}`, role: "group", "aria-label": typeof label === 'string' ? label : undefined, children: [_jsxs("div", { className: `audio-player__panel ${displayedPlaying ? "is-playing" : ""} ${isFetchingUrl ? "is-loading" : ""} ${stateLocal !== "default" ? "is-revealed" : ""}`, children: [isFetchingUrl ? (_jsxs("div", { className: "audio-player__loading", role: "status", "aria-live": "polite", children: [_jsx("span", { className: "audio-player__loading-spinner", "aria-hidden": "true" }), _jsx("span", { className: "audio-player__loading-text", children: t(`training.audioStatus.${fetchDebugStatus}`, { defaultValue: STATUS_MESSAGES[fetchDebugStatus] }) })] })) : null, stateLocal === "active" ? (_jsx("button", { className: "audio-player__button", type: "button", onClick: (e) => { 듣기초점옮기기Ref.current = document.activeElement === e.currentTarget; hideListenTip(); handleToggle(); }, "aria-label": typeof label === 'string' ? label : t('training.listen', '듣기'), onMouseEnter: showListenTip, onMouseLeave: hideListenTip, 
+    return (_jsxs("div", { className: `audio-player ${isDisabled ? 'is-disabled' : ''}${className ? ` ${className}` : ''}`, role: "group", "aria-label": typeof label === 'string' ? label : undefined, children: [_jsxs("div", { className: `audio-player__panel ${displayedPlaying ? "is-playing" : ""} ${isFetchingUrl ? "is-loading" : ""} ${stateLocal !== "default" ? "is-revealed" : ""}`, children: [isFetchingUrl ? (_jsxs("div", { className: "audio-player__loading", role: "status", "aria-live": "polite", children: [_jsx("span", { className: "audio-player__loading-spinner", "aria-hidden": "true" }), _jsx("span", { className: "audio-player__loading-text", children: t(`training.audioStatus.${fetchDebugStatus}`, { defaultValue: STATUS_MESSAGES[fetchDebugStatus] }) })] })) : null, stateLocal === "active" ? (_jsx("button", { className: "audio-player__button", type: "button", 
+                        /* 막힌 단계(아직 차례가 아닌 듣기·합성 주소를 받는 중)는 CSS pointer-events 로만 막아, Tab 으로 와서 Enter 를
+                           누르면 소리를 받으러 가거나 "가져오지 못했습니다" 를 띄웠다 — 마우스와 같게 키보드도 막는다 */
+                        disabled: isDisabled, 
+                        // 키보드로 눌렀을 때만 초점을 옮긴다 — 마우스로 누른 사람에게 '재생 / 멈춤' 초점 툴팁이 뜨지 않게
+                        onClick: () => { 듣기초점옮기기Ref.current = 키보드로눌렀나(); hideListenTip(); handleToggle(); }, "aria-label": typeof label === 'string' ? label : t('training.listen', '듣기'), onMouseEnter: showListenTip, onMouseLeave: hideListenTip, 
                         // 키보드로 이 버튼에 오면 마우스와 동일하게 안내를 띄운다
                         onFocus: showListenTip, onBlur: hideListenTip, children: _jsx("span", { ref: listenBtnRef, className: "audio-player__button-triangle-wrap", children: _jsx("svg", { className: "audio-player__button-triangle", viewBox: "0 0 24 24", "aria-hidden": "true", children: _jsx("path", { ref: triPathRef, d: "M13.2 7.7 L16.5 9.85 Q20.2 12 16.5 14.15 L10 18.3 Q7 19.7 7 16.3 L7 7.7 Q7 4.3 10 5.7 L13.2 7.7" }) }) }) })) : null, listenBtnRect && (_jsx(InfoTooltip, { anchorRect: listenBtnRect, text: typeof label === 'string' && label ? label : t('training.listenLabel', '문장 듣기'), offset: 8 })), _jsxs("div", { className: `audio-player__play ${stateLocal === "playMode" || displayedPlaying ? "is-visible" : ""}`, children: [_jsxs("div", { ref: btnsRef, className: "audio-player__buttons", children: [_jsx(Button, { htmlType: "button", size: 32, showTooltipInfo: true, type: "dot", shape: "pill", useBorder: false, icon: "skip-back", onClick: handlePrev, ariaLabel: t('training.prev', '이전'), width: "60px", variant: "transparent-white", "aria-hidden": "true", tabIndex: -1, disabled: stateLocal !== 'playMode' }), _jsx(Button, { htmlType: "button", size: 32, showTooltipInfo: true, type: "dot", shape: "pill", useBorder: false, icon: displayedPlaying ? "pause" : "play", onClick: handleToggle, ariaLabel: t('common.playPause', '재생 / 멈춤'), width: "60px", variant: "transparent-white", disabled: stateLocal !== 'playMode' }), _jsx(Button, { htmlType: "button", size: 32, showTooltipInfo: true, type: "dot", shape: "pill", useBorder: false, icon: "square", onClick: handleStop, ariaLabel: t('training.stop', '정지'), width: "60px", variant: "transparent-white", "aria-hidden": "true", tabIndex: -1, disabled: stateLocal !== 'playMode' }), sourceButtonCount > 1 ? (_jsx("div", { ref: sourceButtonsRef, className: "audio-player__source-buttons", children: Array.from({ length: sourceButtonCount }).map((_, idx) => (_jsx(Button, { htmlType: "button", size: 32, type: "dot", shape: "pill", useBorder: false, label: String(idx + 1), onClick: () => { try {
                                                 handleJumpTo(idx);

package/dist/packages/core/src/components/Training/TrainingStepTextBox.js

@@ -2,6 +2,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useTranslation } from 'react-i18next';
+import { 키보드로눌렀나 } from '../../hooks/inputModality';
 import Button from '../Button';
 import Toast from '../Toast';
 import { useFontScale } from '../../hooks';
@@ -34,7 +35,8 @@ export default function TrainingStepTextBox({ context, state = "disabled", theme
     const 상자Ref = useRef(null);
     const 펼친뒤초점Ref = useRef(false);
     const handleActivate = useCallback(() => {
-        펼친뒤초점Ref.current = !!상자Ref.current && 상자Ref.current.contains(document.activeElement);
+        // 키보드로 눌렀을 때만 — 마우스로 눌렀는데 옮기면 '글자 크기 감소' 초점 툴팁이 떴다
+        펼친뒤초점Ref.current = 키보드로눌렀나() && !!상자Ref.current && 상자Ref.current.contains(document.activeElement);
         setLocalStatus("active");
     }, []);
     const handleNoticeClose = useCallback(() => setNoticeMessage(''), []);

package/dist/packages/core/src/components/Training/WordTablePopup.js

@@ -51,7 +51,15 @@ export default function WordTablePopup({ items, words, title, subtitle, emptyTex
        새 함수 → 알림 이 끝없이 돈다. 부모가 어떻게 짜든 안 돌게 한다. */
     const notifyRef = useRef(onScoreChange);
     useEffect(() => { notifyRef.current = onScoreChange; });
-    useEffect(() => { notifyRef.current?.(marksForSave(marks)); }, [marks]);
+    // 처음 열 때는 알리지 않는다 — 아무것도 안 매겼는데 onScoreChange({}) 가 나갔다
+    const 첫알림Ref = useRef(true);
+    useEffect(() => {
+        if (첫알림Ref.current) {
+            첫알림Ref.current = false;
+            return;
+        }
+        notifyRef.current?.(marksForSave(marks));
+    }, [marks]);
     /* 표에는 지운 칸(null)이 빠진 것만 넘긴다 — 표는 "매겨진 것"만 알면 된다. */
     const 표에줄채점 = useMemo(() => marksForSave(marks), [marks]);
     // 인쇄 — WordTable 내부 콘텐츠(.word-table 아래 그리드)를 격리 iframe으로 출력한다.

package/dist/packages/core/src/components/Training/useAudioPreview.js

@@ -1,6 +1,7 @@
 'use client';
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { resolveSoundPath, getSignedOrPublicUrl, downloadSound } from '../../utils/storage';
+import { claimSound, stopSoundIfOwner } from './currentSound';
 function derivePreviewMeta(trainingData, typeKey) {
     if (!trainingData)
         return { previewCodes: [], previewBucket: null };
@@ -51,6 +52,9 @@ export function useAudioPreview(trainingData, typeKey) {
     const [resolved, setResolved] = useState({ key: '', urls: [] });
     const previewAudioRef = useRef(null);
     const playingRef = useRef(false);
+    /* 지금 미리 듣기를 멈추는 함수 — 스피커 자물쇠(currentSound.ts)에 건다. 다른 블록 미리 듣기·훈련 소리가 울리면 이것이 불린다.
+       전에는 자물쇠에 참여하지 않아 바구니의 블록 둘을 잇달아 누르면 두 문장이 함께 울렸다. */
+    const 멈춤Ref = useRef(null);
     const previewBtnRef = useRef(null);
     const [previewHover, setPreviewHover] = useState(false);
     // downloadSound()로 만든 blob URL만 추적 — getSignedOrPublicUrl()이 반환하는 http(s) URL은
@@ -129,6 +133,8 @@ export function useAudioPreview(trainingData, typeKey) {
         e.stopPropagation();
         e.preventDefault();
         if (playingRef.current) {
+            if (멈춤Ref.current)
+                stopSoundIfOwner(멈춤Ref.current);
             playingRef.current = false;
             try {
                 previewAudioRef.current?.pause();
@@ -141,6 +147,18 @@ export function useAudioPreview(trainingData, typeKey) {
         const urls = previewUrls.filter(Boolean);
         if (!urls.length)
             return;
+        // pause() 만으로는 ended 가 오지 않아 기다리던 약속이 풀리지 않는다 — 멈출 때 풀어 반복을 끝낸다
+        let 기다림풀기 = null;
+        const 멈춤 = () => {
+            playingRef.current = false;
+            try {
+                previewAudioRef.current?.pause();
+            }
+            catch { }
+            기다림풀기?.();
+        };
+        멈춤Ref.current = 멈춤;
+        const release = claimSound(멈춤);
         playingRef.current = true;
         setPlaying(true);
         for (let i = 0; i < previewUrls.length; i++) {
@@ -152,6 +170,7 @@ export function useAudioPreview(trainingData, typeKey) {
             setPlayingIndex(i);
             try {
                 await new Promise((resolve, reject) => {
+                    기다림풀기 = resolve;
                     const audio = new Audio(url);
                     previewAudioRef.current = audio;
                     audio.onended = () => resolve();
@@ -163,13 +182,19 @@ export function useAudioPreview(trainingData, typeKey) {
                 break;
             }
         }
-        playingRef.current = false;
-        setPlaying(false);
-        setPlayingIndex(-1);
+        release();
+        if (멈춤Ref.current === 멈춤) {
+            멈춤Ref.current = null;
+            playingRef.current = false;
+            setPlaying(false);
+            setPlayingIndex(-1);
+        }
     }, [previewUrls]);
     // Pause and release audio on unmount
     useEffect(() => {
         return () => {
+            if (멈춤Ref.current)
+                stopSoundIfOwner(멈춤Ref.current);
             playingRef.current = false;
             try {
                 previewAudioRef.current?.pause();

package/dist/packages/core/src/components/Word/WordSearchResultBlock.js

@@ -11,7 +11,8 @@ import Dropdown from '../Dropdown';
 import Pagination from '../Pagination';
 import WordImageTooltip from '../Tooltip/WordImageTooltip';
 import { useHoverAnchor } from '../../hooks/useHoverAnchor';
-import { matchesWordQuery } from '../../utils/koreanSyllable';
+import { makeWordQueryMatcher } from '../../utils/koreanSyllable';
+const 가나다 = new Intl.Collator('ko');
 import { withIga, withEulReul } from '../../utils/josa';
 /** @public */
 export default function WordSearchResultBlock({ titleIcon, resultCount, resultUnit, searchQuery, items, groups, selected = [], onSelect, maxSelect, onClearSelection, onPrint, onPrintEmpty, className, emptyHint, sectionType = 'page', disc, notice, }) {
@@ -61,6 +62,21 @@ export default function WordSearchResultBlock({ titleIcon, resultCount, resultUn
         value: v, label: t('wordSearch.pageSize', { count: Number(v), defaultValue: `${v}개씩 보기` }),
     })), [t]);
     const firstWord = (it) => it.words[0];
+    /* '시작 우선' 순위는 검색어가 바뀔 때 판별기를 한 번 만들고 항목마다 한 번만 센다 — 비교할 때마다 검색어를 다시 펼치고
+       localeCompare 를 불러 결과가 바뀔 때 23k 개에 38ms 걸렸다. */
+    const 시작순위 = useMemo(() => {
+        const qLen = [...q].length;
+        const m = makeWordQueryMatcher(q);
+        const memo = new Map();
+        return (it) => {
+            let r = memo.get(it);
+            if (r === undefined) {
+                r = m((it.words[0]?.label ?? '').slice(0, qLen)) ? 0 : 1;
+                memo.set(it, r);
+            }
+            return r;
+        };
+    }, [q]);
     // 정렬 비교자 — flat/그룹 뷰가 공유한다.
     const sortCompare = useCallback((a, b) => {
         const label = (it) => firstWord(it)?.label ?? '';
@@ -70,9 +86,7 @@ export default function WordSearchResultBlock({ titleIcon, resultCount, resultUn
             // 시작 우선 — 검색어로 시작하는 단어를 위로. 앞 q 글자만 잘라 매칭하면 "첫 음절부터 일치"만
             // 남는다(초성 검색도 동일: 'ㄴ' → '나무'가 위). 동순위는 가나다.
             case 'match': {
-                const qLen = [...q].length;
-                const rank = (it) => matchesWordQuery(label(it).slice(0, qLen), q) ? 0 : 1;
-                return rank(a) - rank(b) || label(a).localeCompare(label(b), 'ko');
+                return 시작순위(a) - 시작순위(b) || 가나다.compare(label(a), label(b));
             }
             case 'ganada': return label(a).localeCompare(label(b), 'ko');
             case 'ganada_desc': return label(b).localeCompare(label(a), 'ko');
@@ -82,7 +96,7 @@ export default function WordSearchResultBlock({ titleIcon, resultCount, resultUn
             case 'grade_desc': return grade(b) - grade(a) || label(a).localeCompare(label(b), 'ko');
             default: return 0;
         }
-    }, [effectiveSortKey, q]);
+    }, [effectiveSortKey, 시작순위]);
     const sortedItems = useMemo(() => items.slice().sort(sortCompare), [items, sortCompare]);
     const pageSize = Number(pageSizeStr) || 10;
     // 그룹 뷰(대립쌍표 음소대립)도 flat과 동일하게 정렬·페이지네이션한다 — 그룹 순서를 유지하고 그룹 내부를

package/dist/packages/core/src/components/Word/WordTableBlock.js

@@ -166,7 +166,7 @@ export default function WordTableBlock({ title, titleIcon, disc, items, onSaveCo
         Promise.all(imagePairs.map(([w, h]) => checkImageExists(w, h))).then(results => {
             if (!cancelled)
                 setImageFound(results.some(Boolean));
-        });
+        }, () => { }); // 확인이 거절돼도(리졸버 예외 등) 처리되지 않은 거절로 새지 않게 — 이미지 없음으로 둔다
         return () => { cancelled = true; };
     }, [imagePairs]);
     const hasImage = imagePairs.length > 0 && imageFound;
@@ -288,7 +288,10 @@ export default function WordTableBlock({ title, titleIcon, disc, items, onSaveCo
                             setActiveCell(null);
                         },
                         onClose: handleCloseWordSearch,
-                    }), !hideControls && (_jsx(TableFilterPanel, { hasImage: hasImage, hasColloquial: hasColloquial, contentTypes: contentTypes, orientation: orientation, showOutline: showOutline, cutLine: cutLine, showDivLine: showDivLine, setters: { setContentTypes, setOrientation, setShowOutline, setCutLine, setShowDivLine }, showCutLine: (pagesEnabled ? itemsPerPage : count) > 1, showDivLine2: hasPairs, middleSections: middleSections, extraSelected: middleSelected, onExtraSelect: handleMiddleSelect })), isPaginated && pages ? (_jsx("div", { className: "word-table-block__pages", children: pages.map((page, i) => (_jsx(WordTable, { orientation: orientation, contentTypes: contentTypes, cutLine: cutLine, showOutline: showOutline, showDivLine: showDivLine, count: itemsPerPage, items: page, onRemoveItem: onRemoveItem, contentRef: el => { pageRefs.current[i] = el; }, pageNumber: { current: i + 1, total: pages.length }, pageNumberPosition: pageNumberPosition }, i))) })) : (_jsx(WordTable, { orientation: orientation, contentTypes: contentTypes, cutLine: cutLine, showOutline: showOutline, showDivLine: showDivLine, count: count, items: isEditable ? undefined : (items ?? []), editCells: isEditable ? cells : undefined, activeCell: activeCell, onActivateCell: (isEditable || onAddItem) ? setActiveCell : undefined, onRemoveCell: isEditable ? handleRemove : undefined, onRemoveItem: !isEditable ? onRemoveItem : undefined, onReorder: !isEditable ? onReorder : undefined, showFillerAdd: !!onAddItem, contentRef: contentRef })), inlineNameFields && !hideControls && (_jsxs(Panel, { size: "medium", labelWidth: 64, useBorder: false, useRowBorder: false, className: "word-table-block__meta", children: [_jsx(PanelRow, { variant: "custom", label: t('wordTable.save.nameLabel', '이름'), required: true, align: "vertical", useFullWidth: true, children: _jsx(TextField, { required: true, value: nameValue ?? '', onChange: onNameChange, placeholder: namePlaceholder ? namePlaceholder + t('wordTable.save.autoFillHint', ' (Tab 또는 space 입력시 자동 입력)') : t('wordTable.save.placeholder', '이 단어표에 대한 제목을 입력하세요.'), 
+                    }), !hideControls && (_jsx(TableFilterPanel, { hasImage: hasImage, hasColloquial: hasColloquial, contentTypes: contentTypes, orientation: orientation, showOutline: showOutline, cutLine: cutLine, showDivLine: showDivLine, setters: { setContentTypes, setOrientation, setShowOutline, setCutLine, setShowDivLine }, showCutLine: (pagesEnabled ? itemsPerPage : count) > 1, showDivLine2: hasPairs, middleSections: middleSections, extraSelected: middleSelected, onExtraSelect: handleMiddleSelect })), isPaginated && pages ? (_jsx("div", { className: "word-table-block__pages", children: pages.map((page, i) => (_jsx(WordTable, { orientation: orientation, contentTypes: contentTypes, cutLine: cutLine, showOutline: showOutline, showDivLine: showDivLine, count: itemsPerPage, items: page, onRemoveItem: onRemoveItem, 
+                            /* 쪽이 나뉘면 끌어 옮기기가 통째로 꺼졌다(말귀 단어 찾기: 9개부터). 쪽 안의 자리를 전체 자리로 옮겨 넘긴다 —
+                               쪽을 넘는 이동은 하지 않는다. */
+                            onReorder: onReorder && ((from, to) => onReorder(from + i * itemsPerPage, to + i * itemsPerPage)), contentRef: el => { pageRefs.current[i] = el; }, pageNumber: { current: i + 1, total: pages.length }, pageNumberPosition: pageNumberPosition }, i))) })) : (_jsx(WordTable, { orientation: orientation, contentTypes: contentTypes, cutLine: cutLine, showOutline: showOutline, showDivLine: showDivLine, count: count, items: isEditable ? undefined : (items ?? []), editCells: isEditable ? cells : undefined, activeCell: activeCell, onActivateCell: (isEditable || onAddItem) ? setActiveCell : undefined, onRemoveCell: isEditable ? handleRemove : undefined, onRemoveItem: !isEditable ? onRemoveItem : undefined, onReorder: !isEditable ? onReorder : undefined, showFillerAdd: !!onAddItem, contentRef: contentRef })), inlineNameFields && !hideControls && (_jsxs(Panel, { size: "medium", labelWidth: 64, useBorder: false, useRowBorder: false, className: "word-table-block__meta", children: [_jsx(PanelRow, { variant: "custom", label: t('wordTable.save.nameLabel', '이름'), required: true, align: "vertical", useFullWidth: true, children: _jsx(TextField, { required: true, value: nameValue ?? '', onChange: onNameChange, placeholder: namePlaceholder ? namePlaceholder + t('wordTable.save.autoFillHint', ' (Tab 또는 space 입력시 자동 입력)') : t('wordTable.save.placeholder', '이 단어표에 대한 제목을 입력하세요.'), 
                                     /* PanelRow의 라벨은 시각적으로만 붙어 있고 입력과 연결돼 있지 않아, 낭독기에는
                                        이름 없는 입력으로 읽혔다. placeholder는 자동완성 안내문("Tab 또는 space…")이
                                        섞여 있어 이름으로 부적절하므로 같은 라벨 문구를 넘긴다. */

package/dist/packages/core/src/components/Word/WordTableButton.d.ts

@@ -3,13 +3,13 @@ import type { WordSearchResultItem } from '../../types/wordSearch';
 import './WordTableButton.css';
 /** @public */
 export interface WordTableButtonProps {
-    /** 단어표 내용(썸네일 미리보기 + 개수) */
+    /** 단어표 내용(썸네일 미리보기) */
     items: WordSearchResultItem[];
     /** 단어표 이름 */
     name: string;
     /** 설명 — 제목 아래 body-3로 표시(있을 때만) */
     description?: string;
-    /** 생성일(ISO) — 메타(날짜)에 표시. 없으면 개수만. */
+    /** 생성일(ISO) — 메타(날짜)에 표시. */
     createdAt?: string;
     /** 스토어 발행 배지 표시 */
     published?: boolean;
@@ -43,6 +43,6 @@ export interface WordTableButtonProps {
 }
 /**
  * @public 단어표를 '문서형' 미리보기 카드로 표현하는 컴포넌트.
- * 내용 썸네일(WordTableThumbnail) + 이름 + 날짜·개수 + (발행 배지 / 더보기 / 스토어 푸터).
+ * 내용 썸네일(WordTableThumbnail) + 이름 + 날짜 + (발행 배지 / 더보기 / 스토어 푸터).
  */
 export default function WordTableButton({ items, name, description, createdAt, published, publishedLabel, shared, sharedLabel, isNew, publisherName, publishedAt, likeCount, downloadCount, onPublisherClick, selected, onClick, onMore, titleNode, className, }: WordTableButtonProps): import("react").JSX.Element;

package/dist/packages/core/src/components/Word/WordTableButton.js

@@ -9,7 +9,7 @@ import { formatRelativeTime } from '../../utils/date';
 import './WordTableButton.css';
 /**
  * @public 단어표를 '문서형' 미리보기 카드로 표현하는 컴포넌트.
- * 내용 썸네일(WordTableThumbnail) + 이름 + 날짜·개수 + (발행 배지 / 더보기 / 스토어 푸터).
+ * 내용 썸네일(WordTableThumbnail) + 이름 + 날짜 + (발행 배지 / 더보기 / 스토어 푸터).
  */
 export default function WordTableButton({ items, name, description, createdAt, published, publishedLabel, shared, sharedLabel, isNew, publisherName, publishedAt, likeCount, downloadCount, onPublisherClick, selected, onClick, onMore, titleNode, className, }) {
     const { t } = useTranslation();

package/dist/packages/core/src/components/Word/useWordTableDisplaySettings.js

@@ -43,7 +43,7 @@ export function useWordTableDisplaySettings(items) {
         }
         Promise.all(items.flatMap(item => item.words.map(w => checkImageExists(w.label, w.homonum))))
             .then(results => { if (!cancelled)
-            setHasImage(results.some(Boolean)); });
+            setHasImage(results.some(Boolean)); }, () => { }); // 거절은 이미지 없음으로 둔다
         return () => { cancelled = true; };
     }, [items]);
     /* eslint-enable react-hooks/set-state-in-effect */

package/dist/packages/core/src/components/Word/wordTableBlockTypes.d.ts

@@ -23,7 +23,7 @@ export interface WordTableBlockProps {
     tableName?: string;
     /** 전달하면 외부 데이터 표시 모드, 없으면 편집 모드 */
     items?: WordSearchResultItem[];
-    /** 전달하면 저장 팝업을 내부에서 열고 확인 후 name·items·description을 전달.
+    /** 전달하면 저장하기가 저장 팝업(`renderSavePopup` 이 그림 — 없으면 아무것도 뜨지 않는다)을 열고 확인 후 name·items·description을 전달.
      *  saveAsNew=true면 '다른 이름으로 저장'(수정 대신 새 표 생성)을 뜻한다. */
     onSaveComplete?: (name: string, items: WordSearchResultItem[], description?: string, saveAsNew?: boolean) => void;
     onLoad?: () => void;
@@ -49,7 +49,7 @@ export interface WordTableBlockProps {
     editingName?: string;
     /** 지정하면 인쇄하기 왼쪽에 '취소' 버튼을 표시(PagePopup 닫기 등). */
     onCancel?: () => void;
-    /** 전달하면 카드 드래그로 순서 변경 가능 */
+    /** 전달하면 카드 드래그로 순서 변경 가능. 쪽이 나뉘면 같은 쪽 안에서만 옮기며, 자리는 전체 목록 기준이다. */
     onReorder?: (fromIndex: number, toIndex: number) => void;
     /** display 모드에서도 칸 수 조절 허용 */
     showCellCount?: boolean;

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

@@ -1,7 +1,3 @@
-/**
- * barChartData.ts
- * BarChart의 순수 데이터 계층 — 날짜→월/주/일 막대 데이터 집계 (React 무관).
- */
 /** 막대 하나의 데이터 — a/b 두 계열. a === -1 이면 미래(데이터 없음)로 표시하지 않음.
  *  parts: 다계열 stacked용 계열별 값(있으면 a는 합계로 사용). */
 export interface BarData {
@@ -19,7 +15,9 @@ export type MonthBarData = {
     weekly: BarData[];
     daily: BarData[];
 };
-/** 날짜별 카운트 포인트 — a/b 2계열 또는 parts(다계열 stacked, a는 합계) */
+/** 날짜별 카운트 포인트 — a/b 2계열 또는 parts(다계열 stacked, a는 합계).
+ *  `date` 는 **KST 달력 날짜를 기기 달력 자정 Date 로** 옮긴 것: 시각이면 `parseLocalYmd(toKstYmd(createdAt))`,
+ *  서버가 KST 로 집계한 'YYYY-MM-DD' 면 `parseLocalYmd(log_date)`. */
 export interface ChartPoint {
     date: Date;
     a: number;