@ihabdevteam/core 0.8.0

package/dist/packages/core/src/hooks/useWordTrainingFilter.js

@@ -0,0 +1,549 @@
+'use client';
+import { useCallback, useEffect, useMemo, useRef, useState, createElement } from 'react';
+import { useTranslation } from 'react-i18next';
+import { getViableComposition, countUsableWords } from '../utils/wordTrainingRuntime';
+import { FILTER_ALL_VALUE } from '../types/filterPanel';
+import { useWindowEvent } from './useWindowEvent';
+import FilterSectionInfo from '../components/FilterSectionInfo';
+import { useWordAttributeFilterKeys, buildGradeSection, buildPartOfSpeechSection, buildWordTypeSection } from './useWordAttributeFilter';
+import { matchesFilters } from '../utils/phonemePairSearch';
+import { hasSel } from '../utils/wordContrast';
+/* 글자↔발음 변환과 음절 상수는 wordTrainingFilterModel.ts 로 옮겼다(React 없는 순수 계층).
+   **공개하던 이름은 여기서 그대로 다시 내보낸다** — 가져다 쓰는 쪽은 바뀌지 않는다. */
+import { valueToJamos, NO_CODA, SYLLABLE_MIN, SYLLABLE_COUNTS, syllableValue, parseSyllableValue, syllableToFilter, PART_JAMOS, PHONEME_CLUSTERS, convertComposition, EMPTY_COMPOSITION, } from './wordTrainingFilterModel';
+export { valueToJamos, NO_CODA, SYLLABLE_MIN, syllableToFilter, charToPronValue, pronToCharValue, convertComposition, EMPTY_COMPOSITION, } from './wordTrainingFilterModel';
+// ─── localStorage 지속성 ────────────────────────────────────────────────────
+const LEGACY_STORAGE_KEY = 'wt_filter';
+const storageKey = (groupKey) => `wt_filter_${groupKey}`;
+function loadSavedFilter(groupKey) {
+    try {
+        // 그룹별 저장값 우선, 없으면 레거시 공통 저장값으로 폴백
+        const s = localStorage.getItem(storageKey(groupKey)) ?? localStorage.getItem(LEGACY_STORAGE_KEY);
+        if (s)
+            return JSON.parse(s);
+    }
+    catch { }
+    return null;
+}
+/** 저장값에서 composition 복원 (레거시 choseong → cho 마이그레이션) */
+function readComposition(saved) {
+    const s = saved;
+    if (s?.composition) {
+        return {
+            cho: s.composition.cho ?? null,
+            jung: s.composition.jung ?? null,
+            jong: s.composition.jong ?? null,
+            syllable: s.composition.syllable ?? null,
+        };
+    }
+    if (s?.choseong)
+        return { ...EMPTY_COMPOSITION, cho: s.choseong };
+    return EMPTY_COMPOSITION;
+}
+// ─── 훅 ──────────────────────────────────────────────────────────────────────
+/**
+ * 단어 훈련 그룹별 필터 상태.
+ * @param groupKey  그룹 식별자 (localStorage 키 및 상태 격리에 사용)
+ * @param caps      그룹이 노출할 설정 (난이도/단어구성). 제외 필터는 항상 노출.
+ * @public
+ */
+export function useWordTrainingFilter(groupKey, caps, opts) {
+    const { t, i18n } = useTranslation();
+    // resetOnMount(단어훈련 만들기 등): 진입 시 항상 기본값에서 시작하도록 저장값을 불러오지 않는다.
+    // localStorage 읽기/파싱은 마운트 시 1회만 (lazy init)
+    const [saved] = useState(() => opts?.resetOnMount ? null : loadSavedFilter(groupKey));
+    // 1~4개는 정확히 N개 차이, 5는 "5개 이상"(≥5) 버킷 — 런타임에서 threshold로 처리.
+    // saved.contrastCount는 localStorage에 저장된 이전 세션의 값 — 과거 포맷이나 수동 편집으로
+    // 숫자가 아닌 값이 들어있으면 Number.isFinite로 걸러 NaN이 이후 계산(비교·최소음절수 등)에
+    // 조용히 전파되는 것을 막는다.
+    const rawContrastCount = saved?.contrastCount;
+    const savedContrastCount = typeof rawContrastCount === 'number' && Number.isFinite(rawContrastCount) ? rawContrastCount : 1;
+    const [contrastCount, setContrastCount] = useState(Math.min(5, Math.max(1, savedContrastCount)));
+    // 훈련 음소 그룹 보기 모드 — 'char'(글자 선택) | 'pron'(발음 선택).
+    // composition 값이 모드별(글자=개별 자모, 발음=병합/대표음)로 저장되므로, 모드도 함께 persist 해야 재로드 시 일치한다.
+    const [phonemeView, setPhonemeView] = useState(saved?.phonemeView === 'pron' ? 'pron' : saved?.phonemeView === 'direct' ? 'direct' : 'char');
+    const [composition, setComposition] = useState(() => readComposition(saved));
+    // 타입별 시드 composition — 한 음절 특정(requireSyllable)은 '가'(ㄱ+ㅏ+제외), 그 외는 중립.
+    // 음절 수 고정(fixedSyllable)·종성 제외 고정(fixedNoCoda)이 있으면 그 값을 반영한다.
+    const seedComposition = useCallback(() => caps.requireSyllable
+        ? { cho: 'ㄱ', jung: 'ㅏ', jong: NO_CODA, syllable: caps.fixedSyllable ?? null }
+        : { cho: null, jung: null, jong: caps.fixedNoCoda ? NO_CODA : null, syllable: caps.fixedSyllable ?? null }, [caps.requireSyllable, caps.fixedSyllable, caps.fixedNoCoda]);
+    // 마운트 시 한 번: 고정값이 있는 타입이면 초기 composition도 시드한다(기본 타입이 고정형일 때 대비).
+    /* eslint-disable react-hooks/set-state-in-effect */
+    useEffect(() => {
+        if (!caps.requireSyllable && caps.fixedSyllable == null && !caps.fixedNoCoda)
+            return;
+        setComposition(prev => (prev.cho || prev.jung || prev.syllable != null || prev.jong) ? prev : seedComposition());
+        // 마운트 1회만
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    /* eslint-enable react-hooks/set-state-in-effect */
+    // 난이도(대립 위치)는 훈련 음소 선택에서 자동 유도한다 — 사용자가 별도로 고르지 않는다.
+    // 초성/모음/종성 중 하나라도 선택돼 있으면 그 자리(들)에서만 오답이 다르고 나머지는 고정
+    // (런타임의 posContrast 경로 — wordTrainingRuntime.ts의 buildMultiPartPosContrast). 아무 자리도
+    // 안 골랐으면 무작위. 훈련 음소 선택과 난이도를 별개로 고를 수 있게 하면(예: '초성 ㄱ 선택 +
+    // 모음차이 난이도') 선택한 훈련 음소가 오히려 고정되고 무관한 자리가 바뀌는 정반대 결과가 나온다.
+    const difficulty = useMemo(() => (hasSel(composition.cho) || hasSel(composition.jung) || hasSel(composition.jong)) ? 'count' : 'random', [composition.cho, composition.jung, composition.jong]);
+    // 글자 모드에서 마지막으로 선택돼 있던 모음 자모 — 발음↔글자 왕복 시 병합 버튼(ㅔㅐ 등)의
+    // 대표 자모로 뭉개지지 않고 원래 자모를 정확히 복원하기 위해 별도로 기억해 둔다.
+    const lastCharJungRef = useRef(phonemeView === 'char' ? composition.jung : null);
+    useEffect(() => {
+        if (phonemeView === 'char')
+            lastCharJungRef.current = composition.jung;
+    }, [phonemeView, composition.jung]);
+    // resetOnMount(단어훈련 만들기): '초기화'는 필터를 모두 비운 중립 상태여야 하므로 선택 토글도 OFF로 시작한다.
+    // (기본 ON이면 단음절 음소 합치기 등에서 '이미지 있는 단어만'에 걸려 첫 진입 결과가 0이 된다.)
+    // 단, 카드에 이미지가 필요한 타입(듣고 순서대로 기억하기 등)은 defaultImageOnly로 ON을 요청할 수 있다.
+    const [excludeNoImage, setExcludeNoImage] = useState(opts?.resetOnMount ? !!opts?.defaultImageOnly : (saved?.excludeNoImage ?? true));
+    // 음소 구조 같은 단어만(초성 ㅇ 유무·받침 유무 대립 제외) — 기본 true (reset 시 OFF)
+    const [sameStructureOnly, setSameStructureOnly] = useState(opts?.resetOnMount ? false : (saved?.sameStructureOnly ?? true));
+    // 난이도 등급('1'~'4') 필터 — 배열(다중 선택), 빈 배열은 전체(무제약)
+    const [gradeFilter, setGradeFilter] = useState(Array.isArray(saved?.gradeFilter) ? saved.gradeFilter : []);
+    // 품사/어종 필터 — 단어표·대립쌍표와 동일 라벨 배열(다중 선택). caps로 노출 여부 결정(기본 미노출).
+    const [posFilter, setPosFilter] = useState(Array.isArray(saved?.posFilter) ? saved.posFilter : []);
+    const [wordTypeFilter, setWordTypeFilter] = useState(Array.isArray(saved?.wordTypeFilter) ? saved.wordTypeFilter : []);
+    // 훈련 타입(resetKey) 변경 시 필터를 그 타입 기본값으로 초기화 — 이전 타입의 고정값(음절수/받침/한음절 시드)이
+    // 새 타입으로 새어들어 엉뚱한 결과(예: 3음절 훈련에 1음절 필터가 남아 0건)가 나오는 것을 막는다.
+    // 초기 마운트는 useState 기본값이 이미 처리하므로 ref로 첫 발화를 건너뛴다.
+    const resetKeyRef = useRef(opts?.resetKey);
+    useEffect(() => {
+        if (resetKeyRef.current === opts?.resetKey)
+            return;
+        resetKeyRef.current = opts?.resetKey;
+        setComposition(seedComposition());
+        setExcludeNoImage(false);
+        setSameStructureOnly(false);
+        setGradeFilter([]);
+        setPosFilter([]);
+        setWordTypeFilter([]);
+        setContrastCount(1);
+        // seedComposition은 caps에서 파생 — resetKey와 함께 갱신되므로 deps는 resetKey만 둔다.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [opts?.resetKey]);
+    const attrKeys = useWordAttributeFilterKeys();
+    const [viable, setViable] = useState({ cho: new Set(), jung: new Set(), jong: new Set(), syllable: new Set() });
+    // viable 자모 데이터가 최초 로드되기 전에는 저장된 선택을 해제하지 않는다
+    const [viableReady, setViableReady] = useState(false);
+    // 현재 필터 조건으로 가능한 정답 단어 수 (안내 문구용). null = 계산 전
+    const [wordCount, setWordCount] = useState(null);
+    // count 모드는 위치 무관 음소 차이라 1음절 단어도 2개 차이가 가능 → 음절수 제약 없음(최소 1).
+    const minSyllables = 1;
+    // 훈련할 음소를 고른 슬롯(초성/모음/종성) 수 = 정답↔오답이 달라야 하는 음소의 최소 개수.
+    // 예: 3슬롯 모두 선택하면 최소 3개 음소가 달라야 하므로 '다른 음소의 총 갯수'는 3부터 가능(1·2개 비활성).
+    const minDiffCount = Math.max(1, [composition.cho, composition.jung, composition.jong].filter(Boolean).length);
+    // 최소 개수 미만이 선택돼 있으면 최소값으로 자동 상향 (비활성 옵션이 선택된 채 남지 않도록)
+    /* eslint-disable react-hooks/set-state-in-effect */
+    useEffect(() => {
+        if (contrastCount < minDiffCount)
+            setContrastCount(minDiffCount);
+    }, [minDiffCount, contrastCount]);
+    /* eslint-enable react-hooks/set-state-in-effect */
+    // 필터 변경 시 그룹별 localStorage에 저장. difficulty는 composition에서 파생되므로 저장 대상에서 제외.
+    // resetOnMount 그룹은 매 진입 기본값이어야 하므로 저장하지 않는다(다음 진입에 새어들지 않게).
+    useEffect(() => {
+        if (opts?.resetOnMount)
+            return;
+        try {
+            localStorage.setItem(storageKey(groupKey), JSON.stringify({ contrastCount, composition, excludeNoImage, sameStructureOnly, phonemeView, gradeFilter, posFilter, wordTypeFilter }));
+        }
+        catch { }
+    }, [opts?.resetOnMount, groupKey, contrastCount, composition, excludeNoImage, sameStructureOnly, phonemeView, gradeFilter, posFilter, wordTypeFilter]);
+    const [poolVersion, setPoolVersion] = useState(0);
+    // 단어 풀 갱신 이벤트 구독
+    useWindowEvent('wordpool:update', () => setPoolVersion(v => v + 1));
+    // 언어 전환 시에도 poolVersion을 올려 재생성을 트리거한다.
+    // useWordTrainingDataGeneration의 batch 생성 effect는 (다른 렌더에서 매번 새 배열이 되는)
+    // types를 의존성에서 의도적으로 제외하므로, types의 label/subTitle이 바뀌는 유일한 외부
+    // 요인인 언어 전환을 poolVersion에 반영하지 않으면 perTypeData가 이전 언어로 고정된다.
+    const langRef = useRef(i18n.language);
+    useEffect(() => {
+        if (langRef.current !== i18n.language) {
+            langRef.current = i18n.language;
+            setPoolVersion(v => v + 1);
+        }
+    }, [i18n.language]);
+    // 위치별 사용 가능 자모 계산 (단어 구성 필터를 노출하는 그룹만)
+    useEffect(() => {
+        if (!caps.choseong)
+            return;
+        let cancelled = false;
+        getViableComposition({ difficulty, excludeNoImage })
+            .then(v => {
+            if (cancelled)
+                return;
+            setViable(v);
+            // 빈 결과 = 단어 풀 미로드 상태. 준비됨으로 보지 않아 저장된 선택을 성급히 해제하지 않는다.
+            if (v.cho.size + v.jung.size + v.jong.size > 0)
+                setViableReady(true);
+        })
+            .catch(() => { if (!cancelled)
+            setViable({ cho: new Set(), jung: new Set(), jong: new Set(), syllable: new Set() }); });
+        return () => { cancelled = true; };
+    }, [caps.choseong, difficulty, excludeNoImage, poolVersion]);
+    // 현재 필터 조건으로 가능한 정답 단어 수 계산 (버튼 선택이 바뀔 때마다)
+    useEffect(() => {
+        let cancelled = false;
+        // 선택된 단어 구성 → CompositionFilter (선택 값을 자모로 분해, 종성 '제외'=jongNone, 음절수 범위 확장)
+        // 병합 버튼(예: 'ㅔㅐ')은 각 자모 OR 매칭, 단일/겹받침은 정확 매칭.
+        const c = composition;
+        const cho = c.cho ? valueToJamos(c.cho) : null;
+        const jung = c.jung ? valueToJamos(c.jung) : null;
+        const jongNone = c.jong === NO_CODA;
+        const jong = jongNone ? null : (c.jong ? valueToJamos(c.jong) : null);
+        const syllable = c.syllable != null ? syllableToFilter(c.syllable) : null;
+        const hasComp = !!(cho || jung || jong || jongNone || syllable);
+        countUsableWords({
+            difficulty: caps.difficulty ? difficulty : null,
+            contrastCount: caps.difficulty ? contrastCount : 1,
+            composition: caps.choseong && hasComp ? { cho, jung, jong, jongNone, syllable } : null,
+            excludeNoImage,
+            sameStructureOnly,
+            // 런타임 카운트는 'direct'(글자 입력=패턴)를 이해하지 못한다 — 철자 기반이므로 'char'로 취급.
+            phonemeView: phonemeView === 'pron' ? 'pron' : 'char',
+            grade: gradeFilter.length > 0 ? gradeFilter : null,
+        })
+            .then(n => { if (!cancelled)
+            setWordCount(n); })
+            .catch(() => { if (!cancelled)
+            setWordCount(null); });
+        return () => { cancelled = true; };
+    }, [caps.choseong, caps.difficulty, difficulty, contrastCount, composition, phonemeView, excludeNoImage, sameStructureOnly, poolVersion, gradeFilter]);
+    // 난이도/풀 변경 시 비활성 자모 선택 해제 (viable 로드 완료 후에만)
+    /* eslint-disable react-hooks/set-state-in-effect */
+    useEffect(() => {
+        if (!viableReady)
+            return;
+        setComposition(prev => {
+            const next = { ...prev };
+            let changed = false;
+            ['cho', 'jung', 'jong'].forEach(part => {
+                const sel = prev[part];
+                if (!sel || sel === NO_CODA)
+                    return; // '제외'(NO_CODA)는 항상 유효
+                if (!valueToJamos(sel).some(j => viable[part].has(j))) {
+                    next[part] = null;
+                    changed = true;
+                }
+            });
+            // 음절 수: viable 하지 않거나, 대립 갯수가 요구하는 최소 음절 수 미만이면 해제.
+            // 단, fixedSyllable(음절 수 고정 타입)은 사용자가 바꿀 수단이 없으므로 여기서도 건드리지 않는다.
+            if (prev.syllable != null && caps.fixedSyllable == null) {
+                if (prev.syllable >= SYLLABLE_MIN) {
+                    if (![...viable.syllable].some(n => n >= SYLLABLE_MIN)) {
+                        next.syllable = null;
+                        changed = true;
+                    }
+                }
+                else if (!viable.syllable.has(prev.syllable) || prev.syllable < minSyllables) {
+                    next.syllable = null;
+                    changed = true;
+                }
+            }
+            return changed ? next : prev;
+        });
+    }, [viable, viableReady, minSyllables, caps.fixedSyllable]);
+    /* eslint-enable react-hooks/set-state-in-effect */
+    // 글자 입력에서 viable 한 자모 집합 (정확 매칭이므로 자모가 풀에 있으면 활성)
+    const partViable = useMemo(() => {
+        const compute = (part) => {
+            const set = new Set();
+            for (const c of PART_JAMOS[part]) {
+                if (viable[part].has(c))
+                    set.add(c);
+            }
+            return set;
+        };
+        return { cho: compute('cho'), jung: compute('jung'), jong: compute('jong') };
+    }, [viable]);
+    // viable 한 음절 수 (정확 매칭 집합 + 'N음절 이상' 활성 여부)
+    const syllableViable = useMemo(() => ({
+        exact: new Set(SYLLABLE_COUNTS.filter(n => viable.syllable.has(n))),
+        min: [...viable.syllable].some(n => n >= SYLLABLE_MIN),
+    }), [viable]);
+    // 번역된 레이블 — 표시용. 내부 로직은 여전히 한국어 상수 키로 동작
+    const LABELS = useMemo(() => ({
+        // 다른 음소 갯수 — 정답과 오답이 서로 다른 음소(자모)의 총 개수 (위치 구분 없음)
+        diffPhonemeCount: t('training.contrast.diffPhonemeCount', { defaultValue: '다른 음소의 총 갯수' }),
+        // 정답 단어 구성 — 음절수/초성/모음/종성 (정답 단어에만 적용)
+        composition: t('wordPairs.composition', '정답 단어 구성'),
+        syllableCount: t('wordPairs.syllableCount', '음절 수'),
+        onset: t('wordPairs.onset', '초성'),
+        vowel: t('wordPairs.vowel', '모음'),
+        coda: t('wordPairs.coda', '종성'),
+        // 훈련할 음소 섹션 라벨 — 대립 종류 항목(onset/vowel/coda)과 별개의 섹션 식별 키
+        phonemeGroup: t('training.filter.phonemeGroup', { defaultValue: '훈련 음절' }),
+        trainOnset: t('training.filter.trainOnset', { defaultValue: '초성' }),
+        trainVowel: t('training.filter.trainVowel', { defaultValue: '모음' }),
+        trainCoda: t('training.filter.trainCoda', { defaultValue: '종성' }),
+        random: t('training.filter.random', '무작위'),
+        exclude: t('wordSearch.filter.exclude', '제외'),
+        // '제외' 섹션의 표시 라벨(식별자는 exclude 유지, 표시만 '선택')
+        selectLabel: t('training.filter.selectSection', { defaultValue: '선택' }),
+        none: t('common.none', '없음'),
+        noImage: t('wordSearch.filter.excludeNoImage', '이미지 없음'),
+        // 선택 섹션 토글 버튼 라벨(긍정형 필터)
+        excludeImage: t('training.filter.excludeImage', { defaultValue: '이미지 있는 단어만' }),
+        sameStructure: t('training.filter.sameStructure', { defaultValue: '음소 구조 같은 단어만' }),
+        // 훈련 음소(초성/모음/종성)의 '전체' — 해당 자리를 제한하지 않음(WordSearchPage의 위치 섹션과
+        // 통일해 locale 값 '무관'이 실제 표기 — '전체/모두'는 "모든 자모가 선택된 상태"로 오해될 수 있다)
+        noLimit: t('training.filter.noLimit', { defaultValue: '무관' }),
+        // 종성 섹션의 '제외' — 받침 있는 단어를 제외(받침 없는 단어만) = NO_CODA
+        codaExclude: t('training.filter.codaExclude', { defaultValue: '제외' }),
+        gradeLabel: t('training.filter.gradeLabel', { defaultValue: '난이도 등급' }),
+    }), [t]);
+    // 구성요소 섹션 라벨 → part 매핑
+    const partByLabel = useMemo(() => ({
+        [LABELS.trainOnset]: 'cho', [LABELS.trainVowel]: 'jung', [LABELS.trainCoda]: 'jong',
+    }), [LABELS]);
+    const infoAction = useCallback((items, title) => createElement(FilterSectionInfo, { title, items }), []);
+    const selectInfoItems = useMemo(() => [
+        t('training.filter.excludeImageInfo', { defaultValue: '이미지 있는 단어만: 단어 중에 이미지가 있는 단어만 결과에 보여줍니다.' }),
+        t('training.filter.sameStructureInfo', { defaultValue: '음소 구조 같은 단어만: 정답과 오답의 음절 구조(글자 수·받침 유무 등)가 같은 결과만 남겨요.' }),
+    ], [t]);
+    const filterSections = useMemo(() => {
+        const sections = [];
+        if (caps.choseong) {
+            // 초성/모음/종성 단일 선택.
+            // 글자 선택(char): 전체 자모를 사전순 버튼 나열(정확 매칭).
+            // 발음 선택(pron): 조음/음성 특성별 클러스터(groups)로 간격 구분, 동음 모음은 병합 버튼, 종성은 '없음' 포함.
+            // groupLabel(phonemeGroup)은 "훈련 음소" 패널 소속을 나타내는 파티션 태그로 사용한다.
+            // 종성 '제외' 버튼(받침 있는 단어 제외 = NO_CODA). '제한 없음' 바로 옆에 노출, 항상 활성.
+            const codaExcludeItem = { value: NO_CODA, displayLabel: LABELS.codaExclude };
+            // 종성 '제외' 고정(fixedNoCoda) — 종성 칸은 '제외'만 활성·선택하고 나머지 자모·'모두'는 비활성화한다.
+            const jongFixedExclude = caps.fixedNoCoda === true;
+            const partSection = (part, label) => {
+                const lockJong = jongFixedExclude && part === 'jong';
+                const base = {
+                    label,
+                    groupLabel: LABELS.phonemeGroup,
+                    // 한 음절 특정 타입은 '모두' 없이 항상 하나를 고르게 한다. 종성 고정 칸은 '모두'를 비활성화.
+                    allOption: !caps.requireSyllable,
+                    allLabel: LABELS.noLimit,
+                    allOptionDisabled: lockJong,
+                };
+                if (phonemeView === 'pron') {
+                    // 클러스터별 버튼 그룹. 병합 버튼(다자모)은 자모 중 하나라도 viable 하면 활성.
+                    // tooltip(조음 정보)은 버튼 hover 시 노출(대립쌍표와 동일).
+                    const groups = PHONEME_CLUSTERS[part].map(cluster => cluster.map(({ v, tooltip }) => {
+                        const jamos = valueToJamos(v);
+                        const disabled = lockJong || !jamos.some(j => viable[part].has(j));
+                        // 병합(다자모) 버튼은 labels 배열로 넘겨 각 자모를 개별 span으로 렌더(표준 라벨 간격).
+                        return jamos.length > 1
+                            ? { value: v, labels: jamos, tooltip, disabled }
+                            : { value: v, tooltip, disabled };
+                    }));
+                    // 종성 필수 타입(requireCoda)은 '제외'(받침 없음) 버튼을 노출하지 않는다.
+                    if (part === 'jong' && !caps.requireCoda)
+                        groups.unshift([codaExcludeItem]);
+                    return { ...base, groups };
+                }
+                const items = PART_JAMOS[part].map(c => (!lockJong && partViable[part].has(c)) ? c : { value: c, disabled: true });
+                return { ...base, items: (part === 'jong' && !caps.requireCoda) ? [codaExcludeItem, ...items] : items };
+            };
+            // 훈련 음소 — 훈련 대상 음소 선택이 가장 중요한 설정이므로 제일 위에 노출.
+            sections.push(partSection('cho', LABELS.trainOnset));
+            sections.push(partSection('jung', LABELS.trainVowel));
+            // 종성: 자모 + '제외'(받침 없는 단어만) 버튼
+            sections.push(partSection('jong', LABELS.trainCoda));
+        }
+        // 난이도 등급 — 정답(후보) 단어에만 적용되는 긍정형 다중 토글. 순서: 난이도 등급 → 품사 → 어종 → 음절 수 → 선택.
+        // 라벨/항목 구성은 단어표·대립쌍표와 공용(useWordAttributeFilter) — gradeLabel은 이 그룹 전용 표시명을 쓰므로
+        // label만 오버라이드하고 나머지(items/allOption 등)는 공용 빌더 그대로 사용.
+        sections.push({
+            ...buildGradeSection(t, attrKeys, {
+                labelAction: infoAction([t('wordPairs.filter.difficultyInfo', { defaultValue: '국립국어원의 기초 어휘 등급이 결과에 반영됩니다.' })]),
+            }),
+            label: LABELS.gradeLabel,
+        });
+        // 품사/어종 — 단어표·대립쌍표와 동일 라벨(공용 훅). caps로 노출 여부 결정(기본 미노출).
+        if (caps.partOfSpeech)
+            sections.push(buildPartOfSpeechSection(attrKeys));
+        if (caps.wordType)
+            sections.push(buildWordTypeSection(attrKeys));
+        // '다른 음소의 총 갯수' UI 제거 — 대립 갯수는 선택한 훈련 음소 수(minDiffCount)로 자동 결정된다.
+        // 음절 수 — 정답+오답 모든 단어가 같은 음절수여야 함(문제 공통 설정).
+        // choseong(훈련 음소) 타입뿐 아니라, fixedSyllable만 지정된 타입(음소 합치기 등 — 훈련 음소
+        // 선택 없이 음절 수만 고정)도 노출한다. fixedSyllable 타입은 그 값(예: 1음절)만 활성·선택하고
+        // 나머지 버튼('전체' 포함)은 비활성화한다 — 섹션이 갑자기 사라지는 것보다 UX가 낫다.
+        if (caps.choseong || caps.fixedSyllable != null) {
+            const fixed = caps.fixedSyllable;
+            sections.push({
+                label: LABELS.syllableCount,
+                items: [
+                    ...SYLLABLE_COUNTS.map(n => ({
+                        value: syllableValue(n),
+                        displayLabel: t('wordPairs.syllableN', { n, defaultValue: '{{n}}음절' }),
+                        // fixedSyllable이면 그 값만 활성. 아니면 풀에 없거나 대립 갯수보다 음절 수가 적으면 비활성.
+                        disabled: fixed != null ? n !== fixed : (!syllableViable.exact.has(n) || n < minSyllables),
+                    })),
+                    // 'N음절 이상' catch-all
+                    {
+                        value: syllableValue(SYLLABLE_MIN),
+                        displayLabel: t('wordPairs.syllableNPlus', { n: SYLLABLE_MIN, defaultValue: '{{n}}음절 이상' }),
+                        disabled: fixed != null ? SYLLABLE_MIN !== fixed : !syllableViable.min,
+                    },
+                ],
+                allOption: true,
+                // fixedSyllable이면 '전체'로 되돌릴 수 없게 비활성화(값이 강제됨)
+                allOptionDisabled: fixed != null,
+            });
+        }
+        // 선택 — choseong 타입은 긍정형 다중 토글(이미지 있는 단어만 / 음소 구조 같은 단어만),
+        // 아니면 이미지 제외만 마지막에 노출. (받침 제외는 종성 섹션의 '제외' 버튼)
+        if (caps.choseong) {
+            sections.push({ label: LABELS.exclude, displayLabel: LABELS.selectLabel, multiple: true, items: [LABELS.excludeImage, LABELS.sameStructure], labelAction: infoAction(selectInfoItems) });
+        }
+        else {
+            sections.push({ label: LABELS.exclude, displayLabel: LABELS.selectLabel, multiple: true, items: [LABELS.excludeImage], labelAction: infoAction([selectInfoItems[0]]) });
+        }
+        return sections;
+    }, [caps.choseong, caps.partOfSpeech, caps.wordType, caps.requireSyllable, caps.fixedSyllable, caps.fixedNoCoda, caps.requireCoda, minSyllables, partViable, viable, phonemeView, syllableViable, LABELS, t, infoAction, selectInfoItems, attrKeys]);
+    const filterSelected = {
+        ...(caps.difficulty ? {
+            [LABELS.diffPhonemeCount]: String(contrastCount),
+        } : {}),
+        ...((caps.choseong || caps.fixedSyllable != null) && composition.syllable != null ? { [LABELS.syllableCount]: syllableValue(composition.syllable) } : {}),
+        ...(caps.choseong && composition.cho ? { [LABELS.trainOnset]: composition.cho } : {}),
+        ...(caps.choseong && composition.jung ? { [LABELS.trainVowel]: composition.jung } : {}),
+        // 종성 값 반영 — NO_CODA면 발음 입력의 '없음' 버튼이 선택 표시된다(제외 토글과도 동기).
+        ...(caps.choseong && composition.jong ? { [LABELS.trainCoda]: composition.jong } : {}),
+        // 선택 섹션 — 활성 토글들의 배열
+        [LABELS.exclude]: [
+            ...(excludeNoImage ? [LABELS.excludeImage] : []),
+            ...(sameStructureOnly ? [LABELS.sameStructure] : []),
+        ],
+        // 난이도 등급 — 선택된 등급들의 라벨 배열('1등급' 등)
+        [LABELS.gradeLabel]: gradeFilter.map(g => t('wordSearch.filter.grade', { n: Number(g), defaultValue: '{{n}}등급' })),
+        // 품사/어종 — 단어표·대립쌍표와 동일하게 선택된 라벨 배열 그대로 노출
+        ...(caps.partOfSpeech ? { [attrKeys.partOfSpeech]: posFilter } : {}),
+        ...(caps.wordType ? { [attrKeys.wordType]: wordTypeFilter } : {}),
+    };
+    const handleFilterSelect = useCallback((value, sectionLabel) => {
+        if (sectionLabel === LABELS.diffPhonemeCount) {
+            const n = Number(value);
+            if (n >= 1)
+                setContrastCount(n);
+        }
+        else if (sectionLabel === LABELS.exclude) {
+            // 다중 토글 — 클릭한 항목만 on/off
+            if (value === LABELS.excludeImage) {
+                setExcludeNoImage(v => !v);
+            }
+            else if (value === LABELS.sameStructure) {
+                setSameStructureOnly(v => !v);
+            }
+        }
+        else if (sectionLabel === LABELS.syllableCount) {
+            setComposition(prev => {
+                // FilterPanel의 '전체' 버튼은 로케일과 무관하게 FILTER_ALL_VALUE를 방출한다 —
+                // 번역된 LABELS.all과 비교하면 en 로케일에서 해제가 안 되고 쓰레기 값이 저장된다.
+                if (!value || value === FILTER_ALL_VALUE)
+                    return { ...prev, syllable: null };
+                const n = parseSyllableValue(value);
+                return { ...prev, syllable: prev.syllable === n ? null : n };
+            });
+        }
+        else if (sectionLabel === LABELS.gradeLabel) {
+            if (!value || value === FILTER_ALL_VALUE) {
+                setGradeFilter([]);
+                return;
+            }
+            const n = value.replace(/\D/g, '');
+            setGradeFilter(prev => prev.includes(n) ? prev.filter(g => g !== n) : [...prev, n]);
+        }
+        else if (sectionLabel === attrKeys.partOfSpeech) {
+            // 품사 — 다중 토글(단어표·대립쌍표와 동일 방식: 라벨 배열)
+            if (!value || value === FILTER_ALL_VALUE) {
+                setPosFilter([]);
+                return;
+            }
+            setPosFilter(prev => prev.includes(value) ? prev.filter(v => v !== value) : [...prev, value]);
+        }
+        else if (sectionLabel === attrKeys.wordType) {
+            // 어종 — 다중 토글(단어표·대립쌍표와 동일 방식: 라벨 배열)
+            if (!value || value === FILTER_ALL_VALUE) {
+                setWordTypeFilter([]);
+                return;
+            }
+            setWordTypeFilter(prev => prev.includes(value) ? prev.filter(v => v !== value) : [...prev, value]);
+        }
+        else {
+            const part = partByLabel[sectionLabel];
+            if (!part)
+                return;
+            setComposition(prev => {
+                // 한 음절 특정 타입: 항상 하나 선택(재클릭/전체 해제 무시).
+                if (caps.requireSyllable)
+                    return (value && value !== FILTER_ALL_VALUE) ? { ...prev, [part]: value } : prev;
+                // '전체' 또는 현재 선택 재클릭 → 해제
+                if (!value || value === FILTER_ALL_VALUE || prev[part] === value)
+                    return { ...prev, [part]: null };
+                return { ...prev, [part]: value };
+            });
+        }
+    }, [LABELS, partByLabel, attrKeys, caps.requireSyllable]);
+    // 품사/어종 판정 — 단어표·대립쌍표가 쓰는 공용 predicate(matchesFilters)를 재사용한다.
+    // filterSelected엔 품사/어종 key만 채워 넘기므로(등급·음절수는 undefined) 그 두 축만 판정한다.
+    // 호출부(TrainingSetPage)는 이 함수로 자신의 후보 단어 필터링(filteredWords)에 품사/어종을 반영한다.
+    const matchesWordAttributes = useCallback((entry) => {
+        if (!caps.partOfSpeech && !caps.wordType)
+            return true;
+        return matchesFilters(entry, {
+            ...(caps.partOfSpeech ? { [attrKeys.partOfSpeech]: posFilter } : {}),
+            ...(caps.wordType ? { [attrKeys.wordType]: wordTypeFilter } : {}),
+        }, attrKeys);
+    }, [caps.partOfSpeech, caps.wordType, posFilter, wordTypeFilter, attrKeys]);
+    // 글자↔발음 전환 — 선택된 초성/모음/종성을 대상 모드의 적절한 버튼으로 매핑해 유지한다.
+    // '글자 입력'(direct)은 버튼 선택이 아니라 패턴 텍스트라 composition 변환 대상이 아니다 —
+    // direct로/에서 전환할 땐 composition을 건드리지 않고 모드만 바꾼다(char↔pron만 매핑 유지).
+    const changePhonemeView = useCallback((next) => {
+        if (next === phonemeView)
+            return;
+        if (next !== 'direct' && phonemeView !== 'direct') {
+            setComposition(c => convertComposition(c, next, lastCharJungRef.current));
+        }
+        setPhonemeView(next);
+    }, [phonemeView]);
+    // 설정 팝업 취소용 — 현재 필터 상태 스냅샷 / 스냅샷으로 복원
+    const getFilterSnapshot = useCallback(() => ({
+        composition, contrastCount, excludeNoImage, sameStructureOnly, phonemeView, gradeFilter,
+    }), [composition, contrastCount, excludeNoImage, sameStructureOnly, phonemeView, gradeFilter]);
+    const restoreFilterSnapshot = useCallback((s) => {
+        setComposition(s.composition);
+        setContrastCount(s.contrastCount);
+        setExcludeNoImage(s.excludeNoImage);
+        setSameStructureOnly(s.sameStructureOnly ?? true);
+        setPhonemeView(s.phonemeView);
+        setGradeFilter(Array.isArray(s.gradeFilter) ? s.gradeFilter : []);
+    }, []);
+    return {
+        difficulty,
+        contrastCount,
+        composition,
+        /** @deprecated composition.cho 사용 — 세션 로그 호환용 */
+        choseong: composition.cho,
+        excludeNoImage,
+        sameStructureOnly,
+        gradeFilter,
+        /** 품사 필터(라벨 배열) — caps.partOfSpeech일 때만 의미 있음 */
+        posFilter,
+        /** 어종 필터(라벨 배열) — caps.wordType일 때만 의미 있음 */
+        wordTypeFilter,
+        /** 현재 품사/어종 필터로 이 단어가 통과하는지 — 호출부가 자신의 후보 단어 목록에 적용 */
+        matchesWordAttributes,
+        poolVersion,
+        filterSections,
+        filterSelected,
+        handleFilterSelect,
+        /** 훈련 음소 그룹 보기 모드 (글자/발음) + 전환(선택 매핑 포함) */
+        phonemeView,
+        setPhonemeView: changePhonemeView,
+        /** 훈련 음소 그룹 헤더 라벨 — groupAction(토글) 주입 대상 식별용 */
+        phonemeGroupLabel: LABELS.phonemeGroup,
+        /** 현재 필터 조건으로 가능한 정답 단어 수 (null = 계산 전) */
+        wordCount,
+        /** 설정 팝업 취소용 — 스냅샷 캡처/복원 */
+        getFilterSnapshot,
+        restoreFilterSnapshot,
+    };
+}

package/dist/packages/core/src/hooks/wordTrainingFilterModel.d.ts

@@ -0,0 +1,61 @@
+import type { CompositionPart } from '../utils/koreanSyllable';
+import { type PhonemeGroupItem } from '../utils/phonemeGroups';
+export declare const FULL_CHOSEONG: ("ㄱ" | "ㄲ" | "ㄴ" | "ㄷ" | "ㄸ" | "ㄹ" | "ㅁ" | "ㅂ" | "ㅃ" | "ㅅ" | "ㅆ" | "ㅇ" | "ㅈ" | "ㅉ" | "ㅊ" | "ㅋ" | "ㅌ" | "ㅍ" | "ㅎ")[];
+export declare const FULL_JUNGSEONG: ("ㅏ" | "ㅐ" | "ㅑ" | "ㅒ" | "ㅓ" | "ㅔ" | "ㅕ" | "ㅖ" | "ㅗ" | "ㅘ" | "ㅙ" | "ㅚ" | "ㅛ" | "ㅜ" | "ㅝ" | "ㅞ" | "ㅟ" | "ㅠ" | "ㅡ" | "ㅢ" | "ㅣ")[];
+export declare const FULL_JONGSEONG: ("ㄱ" | "ㄲ" | "ㄴ" | "ㄷ" | "ㄹ" | "ㅁ" | "ㅂ" | "ㅅ" | "ㅆ" | "ㅇ" | "ㅈ" | "ㅊ" | "ㅋ" | "ㅌ" | "ㅍ" | "ㅎ" | "ㄳ" | "ㄵ" | "ㄶ" | "ㄺ" | "ㄻ" | "ㄼ" | "ㄽ" | "ㄾ" | "ㄿ" | "ㅀ" | "ㅄ")[];
+/** 선택 값(자모 문자열, 병합 버튼은 다자모)을 실제 매칭 자모 배열로 분해. NO_CODA는 빈 배열. */
+export declare const valueToJamos: (v: string) => string[];
+/** 종성 '제외'(받침 없는 단어만) 선택을 나타내는 센티넬 값 */
+export declare const NO_CODA = "__NO_CODA__";
+/** 음절 수 필터 — 정확 매칭 버튼 */
+export declare const SYLLABLE_COUNTS: number[];
+/** '{{n}}음절 이상' catch-all 의 기준값. composition.syllable === SYLLABLE_MIN 이면 "N음절 이상" 의미 */
+export declare const SYLLABLE_MIN = 5;
+/** catch-all(≥SYLLABLE_MIN)을 실제 필터 배열로 확장할 때의 상한 */
+export declare const SYLLABLE_MAX = 12;
+/** 음절 수 버튼 value 접두어 (단일 문자 dot 스타일 회피 + 숫자 파싱용) */
+export declare const SYLLABLE_PREFIX = "SYL_";
+export declare const syllableValue: (n: number) => string;
+export declare const parseSyllableValue: (v: string) => number;
+/** composition.syllable 선택값을 실제 매칭용 음절 수 배열로 변환 (SYLLABLE_MIN 이상은 범위로 확장) */
+export declare function syllableToFilter(syllable: number): number[];
+/** 글자 입력 — 구성요소 종류별 전체 자모 목록(사전순) */
+export declare const PART_JAMOS: Record<CompositionPart, string[]>;
+/**
+ * 발음 입력 — 조음/음성 특성별 클러스터. 각 항목이 버튼 1개(v=값, tooltip=조음 정보)이며,
+ * 간격으로 클러스터를 구분한다. 다자모 값(예: 'ㅔㅐ')은 동음 병합 버튼으로 해당 자모 전부를 매칭(OR)한다.
+ * 조음 정보(양순음 등)는 대립쌍표와 동일하게 버튼 hover 시 tooltip으로 노출한다.
+ *
+ * 그룹 데이터 자체는 utils/phonemeGroups의 표준 단일 출처(PHONEME_GROUPS)에서 파생한다(대립쌍표와 공용).
+ * 훈련측 값 인코딩은 병합 문자열(v = jamos.join('')) — 렌더 시 valueToJamos로 각 자모를 복원한다.
+ */
+export type PronItem = {
+    v: string;
+    tooltip: string;
+};
+export declare const toPronRows: (rows: PhonemeGroupItem[][]) => PronItem[][];
+export declare const PHONEME_CLUSTERS: Record<CompositionPart, PronItem[][]>;
+export declare const JUNG_CHAR_TO_PRON: Record<string, string>;
+export declare const CHO_PRON_SET: Set<string>;
+/** 글자→발음: 자모를 해당 발음 버튼 값으로. 대응 버튼이 없으면 null(선택 해제). */
+export declare function charToPronValue(part: CompositionPart, jamo: string): string | null;
+/**
+ * 발음→글자: 병합 버튼(예: 'ㅔㅐ')은 여러 자모를 하나로 묶으므로 되돌릴 대표 자모가 모호하다.
+ * preferredJamo(전환 직전 글자 모드에서 실제 선택돼 있던 자모)가 병합 그룹에 포함되면 그걸
+ * 그대로 복원하고, 없으면(예: 발음 모드에서 새로 선택한 경우) 첫 자모로 대체한다.
+ * 이걸 생략하면 ㅐ 선택 → 발음 전환('ㅔㅐ') → 글자 전환 시 항상 ㅔ로 바뀌는(자모가 조용히
+ * 다른 글자로 뒤바뀌는) 문제가 생긴다.
+ */
+export declare function pronToCharValue(part: CompositionPart, value: string, preferredJamo?: string | null): string;
+/** 모드 전환 시 composition의 초성/모음/종성을 대상 모드 값으로 변환. 종성 '없음'(NO_CODA)은 유지. */
+export declare function convertComposition(c: WordComposition, to: 'char' | 'pron', preferredCharJung?: string | null): WordComposition;
+/** 정답 단어 구성 선택 상태 (정답 단어에만 적용 — 오답은 대립 관계로 결정) */
+export interface WordComposition {
+    cho: string | null;
+    jung: string | null;
+    jong: string | null;
+    /** 음절 수 (null = 전체) */
+    syllable: number | null;
+}
+/** @public 아무것도 안 고른 상태 — 시험이 기준값으로 쓴다. */
+export declare const EMPTY_COMPOSITION: WordComposition;