@ihabdevteam/core 0.8.0

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

@@ -0,0 +1,229 @@
+'use client';
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from '../../utils/cx';
+import { forwardRef, useCallback, useState, useEffect, useImperativeHandle, useRef } from 'react';
+import { useTranslation } from 'react-i18next';
+import Button from '../Button';
+import Badge from '../Badge';
+import useMediaQuery from '../../hooks/useMediaQuery';
+import { getImageResolver } from '../../utils/imageConfig';
+import { useWordImage } from '../../hooks/useWordImage';
+import { getTTSUrlResolver, getTTSFallbackUrlResolver } from '../../utils/ttsConfig';
+import { claimSound } from './currentSound';
+import SymbolSvg from '../../logo/Symbol_speechear_black.svg';
+import { resolveAssetUrl } from '../../utils/assets';
+import './TrainingWordCard.css';
+const symbolSrc = (typeof SymbolSvg === 'string' && SymbolSvg)
+    || resolveAssetUrl('logo/Symbol_speechear_black.svg');
+/** @public */
+const TrainingWordCard = forwardRef(function TrainingWordCard({ item, disabled = false, onPlayDone, selectable = false, selected = false, onSelect, flipDelay = 0, hideLabel = false, hideAudio = false, orderRank = null }, ref) {
+    const { t } = useTranslation();
+    const label = item.word || item.title || '';
+    // 단어가 없으면(빈 카드) 뒷면(로고)을 보여준다 — disabled와 동일하게 뒤집는다.
+    const showBack = disabled || !label;
+    const rawAudioSrc = item.audio ?? item.sound ?? item.audioKey;
+    // ── 발음 ──
+    const subLabel = item.subLabel || item.pronunciation || '';
+    const colloquialLabel = item.colloquialLabel || '';
+    // ── 앞면 표시값 유지 ──
+    // 단어가 비면 뒷면으로 플립되는데, 그 애니메이션 동안 앞면이 '단어·발음 없이' 돌아가면 어색하다.
+    // 플립 트리거(showBack)는 현재 값으로 두되, 앞면에 그릴 내용은 '마지막으로 채워졌던' 값을 유지한다.
+    const [front, setFront] = useState({ label, subLabel, colloquialLabel, homonum: item.homonum });
+    if (label && front.label !== label) {
+        setFront({ label, subLabel, colloquialLabel, homonum: item.homonum });
+    }
+    // ── 재생 상태 ──
+    const audioRef = useRef(null);
+    const isMobile = useMediaQuery('(max-width: 767px)');
+    const [playing, setPlaying] = useState(false);
+    const [audioUrl, setAudioUrl] = useState('');
+    // ── 이미지 ── (앞면 유지값 기준 — 플립 동안 이미지도 유지)
+    const imageUrl = getImageResolver()?.(front.label, front.homonum) ?? item.image ?? '';
+    const { imgRef, loading: imgLoading, hasImage, onLoad: handleImgLoad, onError: handleImgError } = useWordImage(imageUrl);
+    // ── 오디오 URL 준비 ──
+    useEffect(() => {
+        let cancelled = false;
+        const resolveAudio = async () => {
+            // 1) 직접 URL / 객체 src
+            if (rawAudioSrc) {
+                if (typeof rawAudioSrc === 'string') {
+                    if (rawAudioSrc.startsWith('http') || rawAudioSrc.includes('/')) {
+                        setAudioUrl(rawAudioSrc);
+                        return;
+                    }
+                }
+                else if (typeof rawAudioSrc === 'object' && !Array.isArray(rawAudioSrc)) {
+                    const src = rawAudioSrc.src;
+                    if (src) {
+                        setAudioUrl(src);
+                        return;
+                    }
+                }
+            }
+            // 2) TTS URL 리졸버
+            const resolver = getTTSUrlResolver();
+            if (resolver && label) {
+                try {
+                    const url = await Promise.resolve(resolver(label));
+                    if (!cancelled && url)
+                        setAudioUrl(url);
+                }
+                catch { }
+            }
+        };
+        resolveAudio();
+        return () => { cancelled = true; };
+    }, [rawAudioSrc, label]);
+    // ── 언마운트 시 오디오 정리 ──
+    useEffect(() => {
+        return () => {
+            try {
+                audioRef.current?.pause();
+            }
+            catch { }
+            audioRef.current = null;
+        };
+    }, []);
+    // speechSynthesis 재생 — 종료(또는 미지원 환경) 시 resolve. '모두 듣기' 순차 재생을 위해 Promise로 대기 가능하게 한다.
+    const playSpeechSynthesis = useCallback(() => {
+        return new Promise((resolve) => {
+            if (typeof window !== 'undefined' && window.speechSynthesis && label) {
+                setPlaying(true);
+                window.speechSynthesis.cancel();
+                const utt = new SpeechSynthesisUtterance(label);
+                utt.lang = 'ko-KR';
+                utt.onend = () => { setPlaying(false); try {
+                    onPlayDone?.();
+                }
+                catch { } ; resolve(); };
+                utt.onerror = () => { setPlaying(false); resolve(); };
+                window.speechSynthesis.speak(utt);
+            }
+            else {
+                resolve();
+            }
+        });
+    }, [label, onPlayDone]);
+    // URL 하나를 재생하고 "정상 종료됐는지"로 resolve. 종료 경로(ended/error/reject)는 한 번만
+    // 처리한다 — audio.play() reject와 error 이벤트가 동시에 나는 경우가 있어, 가드가 없으면
+    // 폴백이 두 번 걸려 '모두 듣기' 순차 재생에서 소리가 겹친다.
+    const playUrl = useCallback((url) => {
+        return new Promise((resolve) => {
+            let settled = false;
+            const fail = () => { if (settled)
+                return; settled = true; setPlaying(false); resolve(false); };
+            try {
+                const audio = new Audio(url);
+                audioRef.current = audio;
+                audio.onended = () => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    setPlaying(false);
+                    try {
+                        onPlayDone?.();
+                    }
+                    catch { }
+                    resolve(true);
+                };
+                audio.onerror = fail;
+                audio.play().catch(fail);
+            }
+            catch {
+                fail();
+            }
+        });
+    }, [onPlayDone]);
+    // 오디오 재생 핵심 로직 — 종료 시 resolve. 클릭 핸들러와 ref로 노출되는 play() 양쪽에서 공유.
+    // 재생 우선순위: ① 정식 음원 URL → ② 앱이 등록한 런타임 합성 폴백(예: Gemini-TTS) →
+    // ③ 브라우저 speechSynthesis. ②가 있으면 아직 음원이 없는 단어도 표준발음으로 들린다.
+    const playAudio = useCallback(async () => {
+        if (disabled)
+            return;
+        /* 이전 재생을 확실히 끊고 시작한다(겹침 방지).
+    
+           한때 여기서 `audioRef.current?.pause()` 만 불렀다. 그런데 그 ref 는 **이 카드의
+           것**이라, 옆 카드가 울리는 것은 못 멈췄다 — 변별 훈련에서 1번·2번을 잇달아 누르면
+           둘이 함께 울렸다. speechSynthesis 만 전역이라 음원 없는 낱말에서는 멀쩡해 보였고,
+           그래서 증상이 반만 나타났다. 스피커가 하나이므로 자물쇠도 전역에 둔다. */
+        const release = claimSound(() => {
+            try {
+                audioRef.current?.pause();
+            }
+            catch { /* 이미 정리된 경우 */ }
+            try {
+                window.speechSynthesis?.cancel();
+            }
+            catch { /* 미지원 환경 */ }
+            setPlaying(false);
+        });
+        try {
+            window.speechSynthesis?.cancel();
+        }
+        catch { }
+        // 어느 길로 끝나든 자리를 비운다 — 중간에 return 하는 길이 둘 있다
+        try {
+            if (audioUrl) {
+                setPlaying(true);
+                if (await playUrl(audioUrl))
+                    return;
+            }
+            // 정식 음원이 없거나 재생에 실패 → 런타임 합성 폴백
+            const fallbackResolver = getTTSFallbackUrlResolver();
+            if (fallbackResolver && label) {
+                try {
+                    const url = await Promise.resolve(fallbackResolver(label));
+                    if (url) {
+                        setPlaying(true);
+                        if (await playUrl(url))
+                            return;
+                    }
+                }
+                catch { }
+            }
+            await playSpeechSynthesis();
+        }
+        finally {
+            release(); // 다음 사람이 이미 가져갔으면 아무 일도 안 한다
+        }
+    }, [disabled, audioUrl, label, playUrl, playSpeechSynthesis]);
+    useImperativeHandle(ref, () => ({
+        play: () => playAudio(),
+    }), [playAudio]);
+    const handleStopProp = (e) => e.stopPropagation();
+    const handlePlay = useCallback((e) => {
+        e.stopPropagation();
+        if (disabled)
+            return;
+        // 재생 중이면 일시정지
+        if (playing) {
+            try {
+                audioRef.current?.pause();
+            }
+            catch { }
+            try {
+                window.speechSynthesis?.cancel();
+            }
+            catch { }
+            setPlaying(false);
+            return;
+        }
+        void playAudio();
+    }, [disabled, playing, playAudio]);
+    // ── 카드 클래스 ──
+    const cardClass = cx('training-word-card', disabled ? 'training-word-card--disabled' : '', showBack ? 'training-word-card--flipped' : '', selectable ? 'training-word-card--selectable' : '', selected ? 'training-word-card--selected' : '');
+    return (_jsx("div", { className: cardClass, onClick: selectable && !disabled ? onSelect : undefined, role: selectable ? 'button' : undefined, "aria-pressed": selectable ? selected : undefined, 
+        // role="button" 만으로는 키보드로 닿지도, 누르지도 못한다 — div 는 tabIndex 가
+        // 없으면 포커스를 받지 않고 Enter/Space 기본 동작도 없다. 스크린리더에는 버튼으로
+        // 읽히는데 정작 고를 수가 없어, 훈련 문항을 키보드만으로 풀 수 없었다.
+        tabIndex: selectable && !disabled ? 0 : undefined, "aria-disabled": selectable && disabled ? true : undefined, onKeyDown: selectable && !disabled
+            ? (e) => {
+                // Space 는 기본 동작이 스크롤이라 막고, 둘 다 클릭과 같은 선택으로 잇는다.
+                if (e.key === 'Enter' || e.key === ' ' || e.key === 'Spacebar') {
+                    e.preventDefault();
+                    onSelect?.();
+                }
+            }
+            : undefined, children: _jsxs("div", { className: "training-word-card__flipper", style: { transitionDelay: showBack ? '0ms' : `${flipDelay}ms` }, children: [_jsxs("div", { className: "training-word-card__front", children: [selected && (_jsx("div", { className: "training-word-card__selected-badge", onClick: handleStopProp, children: _jsx(Badge, { type: "dot", size: 40, position: "inline", animate: true, icon: orderRank != null ? undefined : 'check', number: orderRank ?? undefined, "aria-label": orderRank != null ? t('training.nthSelected', { n: orderRank }) : t('training.selected', '선택됨') }) })), _jsx("div", { className: "training-word-card__image-wrap", children: hasImage ? (_jsxs(_Fragment, { children: [imgLoading && _jsx("div", { className: "training-word-card__spinner" }), _jsx("img", { ref: imgRef, className: "training-word-card__image", src: imageUrl, alt: front.label || t('common.image', '이미지'), style: { opacity: imgLoading ? 0 : 1 }, onLoad: handleImgLoad, onError: handleImgError })] })) : (_jsx("div", { className: "training-word-card__placeholder" })) }), !hideLabel && (_jsxs("div", { className: "training-word-card__body", children: [_jsx("div", { className: "training-word-card__word", children: front.label }), front.subLabel && (_jsxs("div", { className: "training-word-card__pronunciation", children: ["[", front.subLabel, "]"] })), front.colloquialLabel && (_jsxs("div", { className: "training-word-card__colloquial caption-1", children: ["[", front.colloquialLabel, "]"] }))] })), !hideAudio && (_jsx("div", { className: "training-word-card__bottom", onClick: selectable ? handleStopProp : undefined, children: _jsx(Button, { size: isMobile ? 40 : 48, type: isMobile ? 'dot' : 'bar', icon: playing ? 'pause' : 'play', label: isMobile ? undefined : t('training.playSound', '소리 듣기'), selected: playing, onClick: handlePlay, disabled: disabled, ariaLabel: t('training.playSound', '소리 듣기') }) }))] }), _jsx("div", { className: "training-word-card__back", "aria-hidden": "true", children: _jsx("img", { src: symbolSrc, className: "training-word-card__disabled-symbol", alt: "", draggable: false }) })] }) }));
+});
+export default TrainingWordCard;

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

@@ -0,0 +1,56 @@
+/* 주요 단어 단어표 팝업 */
+/* 콘텐츠 영역을 높이 제한 박스로 만들어(플렉스 체인) 표가 세로로 넘쳐 잘리지 않고 영역에 맞춰 축소되게 한다 */
+.word-table-popup .popup-content__inner {
+  flex: 1;
+  min-height: 0;
+  display: flex;
+  flex-direction: column;
+}
+
+.word-table-popup__body {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-m);
+  flex: 1;
+  min-height: 0;
+}
+
+/* 표 래퍼 — 남는 높이를 차지하고, WordTable(fitHeight)이 이 높이에 맞춰 축소된다 */
+.word-table-popup__table {
+  flex: 1;
+  min-height: 0;
+  display: flex;
+  justify-content: center;
+  align-items: flex-start;
+  overflow: hidden;
+}
+
+/* 페이지 분할 — 페이지별 단어표를 세로로 쌓고, 넘치면 스크롤(fitHeight 미적용, 각 페이지=한 용지) */
+.word-table-popup__pages {
+  flex: 1;
+  min-height: 0;
+  overflow: auto;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: var(--spacing-content, 24px);
+}
+
+@media print {
+  /* 페이지 분할 시 각 단어표를 개별 인쇄 페이지로 강제 개행 */
+  .word-table-popup__pages .word-table {
+    position: static;
+    page-break-after: always;
+    break-after: page;
+  }
+  .word-table-popup__pages .word-table:last-child {
+    page-break-after: auto;
+    break-after: auto;
+  }
+}
+
+.word-table-popup__empty {
+  color: var(--color-gray);
+  padding: var(--spacing-m) 0;
+  text-align: center;
+}

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

@@ -0,0 +1,61 @@
+import { type ReactNode } from 'react';
+import { type PopupProps } from '../Popup/Popup';
+import type { WordSearchResultItem } from '../../types/wordSearch';
+import { type ScoreMark } from '../Word/wordTableScoring';
+import './WordTablePopup.css';
+/** @public */
+export interface WordTablePopupActions {
+    /** 격리 iframe으로 인쇄한다(선택한 용지 방향 반영). */
+    print: () => void;
+    /** 단어표를 새 창으로 연다. */
+    openNewWindow: () => void;
+}
+/** @public */
+export interface WordTablePopupProps {
+    /** 표시할 단어표 항목(저장된 표 등). 지정 시 words보다 우선. */
+    items?: WordSearchResultItem[];
+    /** 표시할 단어 목록(문자열). 각 단어를 한 칸으로 매핑한다. items 미지정 시 사용. */
+    words?: unknown[];
+    /** 팝업 제목. 기본값 '주요 단어'. */
+    title?: ReactNode;
+    /** 부제 — 보통 문제/항목 이름. */
+    subtitle?: ReactNode;
+    /** 단어가 없을 때 표시할 문구. */
+    emptyText?: ReactNode;
+    /** 하단 버튼(닫기/수정 등). 미지정 시 헤더 닫기(X)만. */
+    buttons?: PopupProps['buttons'];
+    /** footer 버튼을 인쇄·새창 액션과 함께 직접 구성한다. 지정 시 buttons·자동 인쇄버튼보다 우선하며,
+     *  닫기/수정 사이에 인쇄/새창을 원하는 순서로 끼워 넣을 수 있다. */
+    renderButtons?: (actions: WordTablePopupActions) => PopupProps['buttons'];
+    /** 자유 배치 footer(좌측 아이콘 액션 + 우측 주 버튼 등)를 인쇄·새창 액션과 함께 직접 구성한다.
+     *  지정 시 buttons/renderButtons보다 우선한다. 반환값은 Popup의 footer(ReactNode 또는 render-prop). */
+    renderFooter?: (actions: WordTablePopupActions) => PopupProps['footer'];
+    /** renderFooter 사용 시 footer 래퍼에 추가할 클래스(정렬·간격 override용). */
+    footerClassName?: string;
+    /** 지정하면 하단에 "인쇄하기"·"새 창으로 보기" 버튼을 추가하고, 이 값을 PDF 저장 기본 파일명으로 쓴다. */
+    printFileName?: string;
+    /** 표 위에 '표 설정'(구성·용지 방향·외곽선 등) FilterPanel을 노출한다. */
+    showSettings?: boolean;
+    /** 채점 켜기 — 낱말마다 ○/△/✕ 를 매길 수 있다. 표시는 이 팝업이 열려 있는 동안만 남는다. */
+    scoring?: boolean;
+    /** 매긴 표시가 바뀔 때 알린다(안 매긴 칸은 빠진다) — 저장은 부모가 한다. */
+    onScoreChange?: (marks: Record<string, ScoreMark>) => void;
+    /** 종이 맨 위에 찍을 한 줄(누구의·언제·무슨 표). 인쇄되는 것은 격자뿐이라
+     *  이것이 없으면 뽑아 둔 종이에 아무 단서도 안 남는다. */
+    printHeader?: string;
+    /** 닫기 직전에 불린다. false 를 돌려주면 닫지 않는다(채점을 버릴지 묻는 용). */
+    beforeClose?: PopupProps['beforeClose'];
+    /** true면 팝업이 열리고 표가 렌더된 직후 인쇄를 1회 자동 시작한다(메뉴 '인쇄하기' 진입용). */
+    autoPrint?: boolean;
+    /** 팝업 패널 추가 클래스(폭 override 등). */
+    className?: string;
+    onClose: () => void;
+}
+/**
+ * 단어를 WordTable(단어표) 형태로 보여주는 팝업.
+ * - `items`: 저장된 단어표 등 완성된 항목 배열
+ * - `words`: 문자열 단어 목록(각 단어 = 한 칸) — 주요 단어 보기 등
+ * 표 내부에는 제목을 두지 않아 팝업 헤더 제목과 중복되지 않는다.
+ * @public
+ */
+export default function WordTablePopup({ items, words, title, subtitle, emptyText, buttons, renderButtons, renderFooter, footerClassName, printFileName, showSettings, autoPrint, className, onClose, scoring, onScoreChange, printHeader, beforeClose }: WordTablePopupProps): import("react").JSX.Element;

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

@@ -0,0 +1,105 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from '../../utils/cx';
+import { useMemo, useRef, useState, useCallback, useEffect } from 'react';
+import { useTranslation } from 'react-i18next';
+import Popup from '../Popup/Popup';
+import Toast from '../Toast';
+import WordTable, { WORD_TABLE_PAPER } from '../WordTable';
+import TableFilterPanel from '../Word/TableFilterPanel';
+import { useWordTablePrint } from '../Word/useWordTablePrint';
+import { useWordTableDisplaySettings } from '../Word/useWordTableDisplaySettings';
+import { pageStartIndexes, markAfterClick, marksForSave, scoreKey } from '../Word/wordTableScoring';
+import './WordTablePopup.css';
+import { useToastState } from '../../hooks/useToastState';
+/**
+ * 단어를 WordTable(단어표) 형태로 보여주는 팝업.
+ * - `items`: 저장된 단어표 등 완성된 항목 배열
+ * - `words`: 문자열 단어 목록(각 단어 = 한 칸) — 주요 단어 보기 등
+ * 표 내부에는 제목을 두지 않아 팝업 헤더 제목과 중복되지 않는다.
+ * @public
+ */
+export default function WordTablePopup({ items, words, title, subtitle, emptyText, buttons, renderButtons, renderFooter, footerClassName, printFileName, showSettings, autoPrint, className, onClose, scoring = false, onScoreChange, printHeader, beforeClose }) {
+    const { t } = useTranslation();
+    // items 우선, 없으면 문자열 words → 한 단어=한 칸으로 매핑
+    const tableItems = useMemo(() => {
+        if (Array.isArray(items))
+            return items;
+        return (Array.isArray(words) ? words : [])
+            .filter((w) => typeof w === 'string' && w.length > 0)
+            .map((w, i) => ({ id: `${w}-${i}`, words: [{ label: w }] }));
+    }, [items, words]);
+    // 표 설정(구성·용지 방향·외곽선·페이지당 개수 등) — showSettings일 때만 FilterPanel로 노출하고, 값은 항상 표에 반영한다.
+    const { settings, filterSections, filterSelected, handleSelect, pages, isPaginated, pageNumberPosition } = useWordTableDisplaySettings(tableItems);
+    /* 쪽마다 첫 칸이 표 전체에서 몇 번째인지 — 쪽 안에서 0부터 다시 세는 번호를
+       표 전체 번호로 옮긴다. */
+    const pageStart = useMemo(() => pageStartIndexes(pages.map(p => p.length)), [pages]);
+    /**
+     * 채점은 **여기 한 곳에만 둔다.**
+     *
+     * 쪽마다 뜨는 표가 저마다 들고 있던 때가 있었는데, 쪽당 칸 수를 바꾸면 칸이 다른 쪽으로
+     * 옮겨 가면서 **표시가 있던 자리를 잃었다** — 요약은 "2칸"인데 화면에는 하나만 보였다.
+     * 실측한 증상이다(가로 8개에서 두 칸을 매기고 4개로 바꾸니 하나가 사라졌다).
+     * 채점은 표 전체에 대한 것이니 표 전체를 아는 이곳이 든다.
+     */
+    const [marks, setMarks] = useState({});
+    const handleMarkClick = useCallback((cellIndex, clicked) => {
+        setMarks(prev => ({ ...prev, [scoreKey(cellIndex)]: markAfterClick(prev[scoreKey(cellIndex)] ?? null, clicked) }));
+    }, []);
+    /* 바뀔 때마다 부모에게 알린다. **콜백을 ref 로 받아 두고 marks 만 지켜본다** —
+       의존성에 콜백을 그대로 넣으면, 부모가 매번 새 함수를 넘길 때 알림 → 부모 상태 변경 →
+       새 함수 → 알림 이 끝없이 돈다. 부모가 어떻게 짜든 안 돌게 한다. */
+    const notifyRef = useRef(onScoreChange);
+    useEffect(() => { notifyRef.current = onScoreChange; });
+    useEffect(() => { notifyRef.current?.(marksForSave(marks)); }, [marks]);
+    /* 표에는 지운 칸(null)이 빠진 것만 넘긴다 — 표는 "매겨진 것"만 알면 된다. */
+    const 표에줄채점 = useMemo(() => marksForSave(marks), [marks]);
+    // 인쇄 — WordTable 내부 콘텐츠(.word-table 아래 그리드)를 격리 iframe으로 출력한다.
+    // (전역 print CSS는 모든 .word-table을 노출하므로 window.print 직접 호출은 다른 표까지 인쇄될 수 있다)
+    // 페이지 분할 시엔 페이지별 ref, 아니면 단일 콘텐츠 ref를 넘긴다.
+    const contentRef = useRef(null);
+    /*
+     * 팝업 차단 안내는 window.alert 이었다. 이 팝업 위에 브라우저 기본 창이 겹쳐 서고
+     * 앱 글꼴·색을 따르지 않아, 같은 이유로 이미 옮겨 놓은 자리들과 맞춘다.
+     */
+    const { toastMessage: toastMsg, toastKey, showWarning, clearToast: handleToastClose } = useToastState('warning');
+    const pageRefs = useRef([]);
+    const getElements = useCallback(() => isPaginated
+        ? pageRefs.current.filter((el) => el !== null)
+        : (contentRef.current ? [contentRef.current] : []), [isPaginated]);
+    const { print: handlePrint, openNewWindow } = useWordTablePrint({
+        getElements,
+        paperW: WORD_TABLE_PAPER[settings.orientation].width,
+        paperH: WORD_TABLE_PAPER[settings.orientation].height,
+        fileName: printFileName ?? '',
+        header: printHeader ?? '',
+        onPopupBlocked: () => showWarning(t('wordTable.popupBlocked', '팝업이 차단되었습니다. 브라우저 설정에서 팝업을 허용해 주세요.')),
+    });
+    const footerButtons = useMemo(() => {
+        // 자유 배치 footer(renderFooter)가 있으면 buttons는 쓰지 않는다(Popup은 buttons 우선이므로 비워야 footer가 렌더된다).
+        if (renderFooter)
+            return undefined;
+        // 부모가 순서를 직접 정하면(renderButtons) 인쇄/새창 액션을 넘겨주고 전적으로 맡긴다.
+        if (renderButtons)
+            return renderButtons({ print: handlePrint, openNewWindow });
+        if (!printFileName)
+            return buttons;
+        const extraButtons = [
+            { label: t('wordTable.openNewWindow', '새 창으로 보기'), variant: 'default', onClick: () => openNewWindow() },
+            { label: t('wordTable.print', '인쇄하기'), variant: 'default', onClick: () => handlePrint() },
+        ];
+        return [...extraButtons, ...(buttons ?? [])];
+    }, [renderFooter, renderButtons, printFileName, buttons, t, handlePrint, openNewWindow]);
+    const customFooter = useMemo(() => (renderFooter ? renderFooter({ print: handlePrint, openNewWindow }) : undefined), [renderFooter, handlePrint, openNewWindow]);
+    // 메뉴 '인쇄하기' 진입: 팝업이 열리고 표가 렌더된 직후 인쇄를 1회 자동 시작.
+    // 짧은 지연은 WordTable 레이아웃 확정용 — 인쇄 iframe 쪽이 이미지 로드는 별도로 기다린다(wordTablePrint).
+    const autoPrintDone = useRef(false);
+    useEffect(() => {
+        if (!autoPrint || autoPrintDone.current)
+            return;
+        autoPrintDone.current = true;
+        const id = window.setTimeout(() => handlePrint(), 100);
+        return () => window.clearTimeout(id);
+    }, [autoPrint, handlePrint]);
+    return (_jsxs(Popup, { title: title ?? t('keyWords.title', '주요 단어'), subtitle: subtitle, size: "large", className: cx('word-table-popup', className), buttons: footerButtons, footer: customFooter, footerClassName: footerClassName, beforeClose: beforeClose, onClose: onClose, children: [tableItems.length > 0 ? (_jsxs("div", { className: "word-table-popup__body", children: [showSettings && (_jsx(TableFilterPanel, { sections: filterSections, selected: filterSelected, onSelect: handleSelect })), isPaginated ? (_jsx("div", { className: "word-table-popup__pages", children: pages.map((page, i) => (_jsx(WordTable, { items: page, orientation: settings.orientation, contentTypes: settings.contentTypes, cutLine: settings.cutLine, showOutline: settings.showOutline, showDivLine: settings.showDivLine, count: settings.count, contentRef: el => { pageRefs.current[i] = el; }, pageNumber: { current: i + 1, total: pages.length }, pageNumberPosition: pageNumberPosition, scoring: scoring, scoreIndexOffset: pageStart[i], marks: 표에줄채점, onMarkClick: handleMarkClick }, i))) })) : (_jsx("div", { className: "word-table-popup__table", children: _jsx(WordTable, { items: tableItems, orientation: settings.orientation, contentTypes: settings.contentTypes, cutLine: settings.cutLine, showOutline: settings.showOutline, showDivLine: settings.showDivLine, count: settings.count, contentRef: contentRef, fitHeight: true, scoring: scoring, marks: 표에줄채점, onMarkClick: handleMarkClick }) }))] })) : (_jsx("p", { className: "word-table-popup__empty body-3", children: emptyText ?? t('keyWords.empty', '추출된 주요 단어가 없습니다.') })), _jsx(Toast, { message: toastMsg, position: "top", onClose: handleToastClose }, toastKey)] }));
+}

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

@@ -0,0 +1,95 @@
+import type { Source } from './trainingStepAudioPlayerTypes';
+/**
+ * 재생 중에 내리는 **판단**들 — 화면도 오디오도 건드리지 않는 순수 계산.
+ *
+ * 원래 `attachAudioListeners` 안에 `try { } catch (e) {}` 로 겹겹이 싸인 채 들어 있었다.
+ * 거기서는 시험을 쓸 방법이 없다 — 진짜 `<audio>` 와 진짜 이벤트가 있어야 도달하고,
+ * 게다가 무엇이 틀려도 catch 가 삼켜서 **틀린 채로 조용히 지나간다.**
+ *
+ * 판단만 떼어 내면 표로 확인할 수 있다. 나머지(이벤트 붙이기, DOM 스타일 쓰기)는
+ * 원래 자리에 그대로 둔다 — 그쪽은 옮겨도 나아지는 것이 없다.
+ */
+/**
+ * 지금 트랙에서 얼마나 왔는가 — 0~1.
+ *
+ * **여러 소리를 이어 붙인 훈련**에서는 `<audio>` 의 duration 이 아니라 **그 트랙의
+ * 길이**로 재야 한다. 이어 붙인 것을 통짜로 재면 두 번째 트랙이 늘 절반 뒤에서
+ * 시작하는 것처럼 보인다.
+ *
+ * 길이를 모르면(0이거나 아직 메타데이터 전) 0을 준다 — 모르는 것을 100%로 그리면
+ * 마커가 끝에 붙어 있다가 튄다.
+ */
+export declare function progressOf({ currentTime, sources, index, audioDuration, }: {
+    currentTime: number;
+    sources: Source[] | null;
+    index: number;
+    /** `<audio>` 가 알려 주는 길이 — 트랙별 길이를 모를 때만 쓴다 */
+    audioDuration: number;
+}): number;
+/**
+ * 한 트랙이 끝났다 — 이어서 틀 것이 있는가.
+ *
+ * `null` 이면 훈련의 한 문항이 끝난 것이고, 숫자면 다음 트랙으로 넘어간다.
+ * 목록이 없거나 마지막이면 `null`.
+ */
+export declare function nextTrackIndex(sources: Source[] | null, index: number): number | null;
+/**
+ * `pause` 이벤트를 흘려보내야 하는가.
+ *
+ * 두 경우는 **사용자가 멈춘 것이 아니다.**
+ *
+ *  1. 소리가 자연히 끝났을 때 — 브라우저는 `ended` **직전에 `pause` 를 먼저 낸다.**
+ *  2. 끝 처리(handleEnd)가 스스로 `pause()` 를 부른 뒤.
+ *
+ * 이걸 안 거르면 화면이 '일시정지'로 잠깐 바뀌었다가 '정지'로 다시 바뀐다 —
+ * 문항이 끝날 때마다 단추가 한 번씩 깜빡인다.
+ */
+export declare function shouldIgnorePause({ ended, completedByEnd, }: {
+    ended: boolean;
+    completedByEnd: boolean;
+}): boolean;
+/**
+ * 소스 목록을 화면이 쓸 **구간(segment)** 목록으로 바꾼다.
+ *
+ * 구간은 파형 아래에 번호 단추로 그려진다 — 여러 소리를 이어 붙인 훈련에서 "2번으로
+ * 건너뛰기"를 할 수 있게 하는 것.
+ *
+ * 세 갈래(단일 TTS·복수 TTS·저장소 소스)가 각자 이 변환을 한 벌씩 들고 있었고,
+ * 그중 하나는 미묘하게 달랐다 — 길이를 `duration: dur` 로 그냥 넘겨 **길이를 모를 때
+ * `undefined` 가 흘러 들어갔다**(나머지 둘은 `|| 0`). 한 벌로 모으면서 0으로 맞춘다.
+ * 길이를 모르는 것과 0인 것은 여기서 같은 뜻이다 — 어차피 그릴 폭이 없다.
+ */
+export declare function buildSegments(sources: Array<{
+    src?: string | null;
+    duration?: number | null;
+}>): {
+    src: string | null | undefined;
+    label: string;
+    color: undefined;
+    duration: number;
+}[];
+/** 소스들의 길이를 다 더한다 — 모르는 것은 0으로 친다 */
+export declare function totalDurationOf(sources: Array<{
+    duration?: number | null;
+}>): number;
+/** 아직 URL 이 없는 상태의 소스 — 곧바로 틀 수 있는 `src` 이거나, 저장소에서 받아 올 `resolvedPath` */
+export interface NormalizedSource {
+    code?: string | null;
+    src?: string | null;
+    resolvedPath?: string;
+}
+/**
+ * 넘어온 소리 지정을 **한 가지 모양으로** 편다.
+ *
+ * 부르는 쪽이 세 가지로 준다 — 이미 주소를 아는 객체, 주소나 경로처럼 생긴 문자열,
+ * 그리고 그냥 **코드**(예: `QQ01`). 코드는 저장소 규칙을 거쳐야 경로가 되므로
+ * `resolvePath` 를 통과시킨다.
+ *
+ * 두 가지를 조용히 버린다 — 빈 값과, 경로를 못 정한 코드다. 버린 것을 오류로 올리지
+ * 않는 이유는 **한 소리가 없다고 훈련 전체를 못 하게 만들 수는 없어서**다. 대신 몇 개를
+ * 버렸는지는 부르는 쪽이 길이를 비교하면 알 수 있다.
+ *
+ * 원래 `fetchAndPrepare` 안의 40줄짜리 for 문이었다. 거기서는 시험을 쓸 수 없었다 —
+ * 이 판단에 닿으려면 네트워크와 오디오 요소가 먼저 필요했다.
+ */
+export declare function normalizeSources(soundSrc: unknown, bucketPath: string | null | undefined, resolvePath: (code: string, bucketHint?: string | null) => string | null): NormalizedSource[];