@ihabdevteam/core 0.8.0

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

@@ -0,0 +1,34 @@
+import { type WordTrainingTypeKey } from '../utils/wordTrainingRuntime';
+import type { DifficultyLevel } from '../utils/koreanSyllable';
+import { type WordComposition } from './useWordTrainingFilter';
+export interface WordTrainingType {
+    key: WordTrainingTypeKey;
+    label: string;
+    icon: string;
+    color: string;
+    subTitle: string;
+}
+interface WordTrainingDataEntry {
+    id: string;
+    name: string;
+    training_type: WordTrainingTypeKey;
+    category_main_code: string;
+    iconColor: string;
+    subTitle: string;
+    items: unknown[];
+    itemCount: number;
+    __empty?: boolean;
+    [k: string]: unknown;
+}
+/**
+ * 필터 조건에 맞춰 훈련 타입별 데이터를 batch로 생성하는 훅.
+ * poolVersion이 증가하면 사전 계산(precompute)도 트리거.
+ */
+/**
+ * @public
+ */
+export declare function useWordTrainingDataGeneration(types: WordTrainingType[], difficulty: DifficultyLevel, contrastCount: number, composition: WordComposition, excludeNoImage: boolean, poolVersion: number, sameStructureOnly?: boolean, phonemeView?: 'char' | 'pron', gradeFilter?: string[]): {
+    perTypeData: Record<string, WordTrainingDataEntry | null>;
+    generating: boolean;
+};
+export {};

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

@@ -0,0 +1,98 @@
+'use client';
+import { useEffect, useState } from 'react';
+import { CAPABILITY, generateRuntimeItems, precomputeCommonCombinations, } from '../utils/wordTrainingRuntime';
+import { valueToJamos, syllableToFilter, NO_CODA } from './useWordTrainingFilter';
+/** 선택된 단어 구성을 실제 매칭용 CompositionFilter로 변환. 선택 없으면 null.
+ *  선택 값을 자모로 분해해 매칭(병합 버튼은 OR, 단일/겹받침은 정확). */
+function toCompositionFilter(c) {
+    const expand = (v) => v ? valueToJamos(v) : null;
+    const cho = expand(c.cho);
+    const jung = expand(c.jung);
+    // 종성 '제외'(NO_CODA)는 받침 없는 단어만 → jongNone. 특정 종성 자모면 그 자모 매칭.
+    const jongNone = c.jong === NO_CODA;
+    const jong = jongNone ? null : expand(c.jong);
+    const syllable = c.syllable != null ? syllableToFilter(c.syllable) : null;
+    if (!cho && !jung && !jong && !jongNone && !syllable)
+        return null;
+    return { cho, jung, jong, jongNone, syllable };
+}
+/**
+ * 필터 조건에 맞춰 훈련 타입별 데이터를 batch로 생성하는 훅.
+ * poolVersion이 증가하면 사전 계산(precompute)도 트리거.
+ */
+/**
+ * @public
+ */
+export function useWordTrainingDataGeneration(types, difficulty, contrastCount, composition, excludeNoImage, poolVersion, sameStructureOnly = true, phonemeView = 'char', gradeFilter = []) {
+    const [perTypeData, setPerTypeData] = useState({});
+    const [generating, setGenerating] = useState(false);
+    const { cho = null, jung = null, jong = null, syllable = null } = composition ?? {};
+    // 단어풀 갱신 시 사전 계산 (백그라운드 fire-and-forget)
+    useEffect(() => {
+        if (poolVersion > 0) {
+            precomputeCommonCombinations(excludeNoImage).catch(() => { });
+        }
+    }, [poolVersion, excludeNoImage]);
+    // 필터 변경 시 전체 타입 batch generation
+    /* eslint-disable react-hooks/set-state-in-effect */
+    useEffect(() => {
+        let cancelled = false;
+        setGenerating(true);
+        (async () => {
+            const compFilter = toCompositionFilter({ cho, jung, jong, syllable });
+            const gradeKey = gradeFilter.length > 0 ? gradeFilter.slice().sort().join(',') : '';
+            const compKey = `${cho ?? ''}_${jung ?? ''}_${jong ?? ''}_${syllable ?? ''}_${gradeKey}`;
+            const results = {};
+            await Promise.all(types.map(async (t) => {
+                const cap = CAPABILITY[t.key];
+                try {
+                    const items = await generateRuntimeItems(t.key, {
+                        difficulty: cap.difficulty ? difficulty : null,
+                        contrastCount: cap.difficulty ? contrastCount : 1,
+                        composition: cap.choseong ? compFilter : null,
+                        count: 5,
+                        excludeNoImage,
+                        sameStructureOnly,
+                        phonemeView,
+                        grade: gradeFilter.length > 0 ? gradeFilter : null,
+                    });
+                    if (items && items.length > 0) {
+                        results[t.key] = {
+                            id: `wt-${t.key}-${difficulty}-${compKey}-${Date.now()}`,
+                            name: t.label,
+                            training_type: t.key,
+                            category_main_code: 'WORD',
+                            iconColor: t.color,
+                            subTitle: t.subTitle,
+                            items,
+                            itemCount: items.length,
+                        };
+                    }
+                    else {
+                        results[t.key] = {
+                            id: `wt-${t.key}-empty`,
+                            name: t.label,
+                            training_type: t.key,
+                            category_main_code: 'WORD',
+                            iconColor: t.color,
+                            subTitle: t.subTitle,
+                            items: [],
+                            itemCount: 0,
+                            __empty: true,
+                        };
+                    }
+                }
+                catch {
+                    results[t.key] = null;
+                }
+            }));
+            if (!cancelled) {
+                setPerTypeData(results);
+                setGenerating(false);
+            }
+        })();
+        return () => { cancelled = true; };
+    }, [difficulty, contrastCount, cho, jung, jong, syllable, excludeNoImage, sameStructureOnly, phonemeView, poolVersion, gradeFilter]); // eslint-disable-line react-hooks/exhaustive-deps
+    /* eslint-enable react-hooks/set-state-in-effect */
+    return { perTypeData, generating };
+}

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

@@ -0,0 +1,91 @@
+import { type FilterPanelSection } from '../types/filterPanel';
+import { type WordComposition } from './wordTrainingFilterModel';
+export { valueToJamos, NO_CODA, SYLLABLE_MIN, syllableToFilter, charToPronValue, pronToCharValue, convertComposition, EMPTY_COMPOSITION, } from './wordTrainingFilterModel';
+export type { WordComposition } from './wordTrainingFilterModel';
+/** 설정 팝업 취소 시 되돌릴 필터 스냅샷 */
+export interface WordFilterSnapshot {
+    composition: WordComposition;
+    contrastCount: number;
+    excludeNoImage: boolean;
+    sameStructureOnly: boolean;
+    phonemeView: 'char' | 'pron' | 'direct';
+    gradeFilter: string[];
+}
+/**
+ * 그룹이 노출할 설정 항목. 그룹에 속한 훈련 타입들의 CAPABILITY 합집합으로 결정.
+ * (제외/이미지 없음 필터는 모든 타입에 적용되므로 항상 노출)
+ * @public
+ */
+export interface WordTrainingFilterCaps {
+    difficulty: boolean;
+    /** 단어 구성(초성/중성/종성) 필터 노출 여부 */
+    choseong: boolean;
+    /** 품사 필터 노출 여부 — 단어표/대립쌍표와 동일 라벨(useWordAttributeFilter 공용). 기본 false. */
+    partOfSpeech?: boolean;
+    /** 어종 필터 노출 여부 — 단어표/대립쌍표와 동일 라벨(useWordAttributeFilter 공용). 기본 false. */
+    wordType?: boolean;
+    /**
+     * 한 음절을 특정해야 하는 타입(듣고 한 음절 포함 단어 맞히기 등)용.
+     * true면 초성/모음/종성의 '모두' 버튼을 없애고 항상 하나가 선택되도록 하며(재클릭 해제 안 됨),
+     * 초기값을 ㄱ+ㅏ+제외('가')로 시드해 재생할 음절이 항상 확정되게 한다.
+     */
+    requireSyllable?: boolean;
+    /**
+     * 음절 수를 특정 값으로 고정해야 하는 타입(음절 합치기 등)용. 설정 시 '음절 수' 필터 섹션 자체를
+     * 노출하지 않고(사용자가 바꿀 수 없음) composition.syllable을 항상 이 값으로 유지한다.
+     */
+    fixedSyllable?: number;
+    /**
+     * 종성을 '제외'(받침 없음)로 고정해야 하는 타입(음소 2개 합치기=초성+중성=CV)용.
+     * 설정 시 종성 필터는 '제외'만 활성·선택되고 나머지 자모·'모두'는 비활성화된다.
+     */
+    fixedNoCoda?: boolean;
+    /**
+     * 종성이 반드시 있어야 하는 타입(음소 3개 합치기=초성+중성+종성=CVC)용.
+     * 설정 시 종성 '제외'(받침 없음) 버튼을 아예 노출하지 않는다.
+     */
+    requireCoda?: boolean;
+}
+/**
+ * 단어 훈련 그룹별 필터 상태.
+ * @param groupKey  그룹 식별자 (localStorage 키 및 상태 격리에 사용)
+ * @param caps      그룹이 노출할 설정 (난이도/단어구성). 제외 필터는 항상 노출.
+ * @public
+ */
+export declare function useWordTrainingFilter(groupKey: string, caps: WordTrainingFilterCaps, opts?: {
+    resetOnMount?: boolean;
+    resetKey?: string;
+    defaultImageOnly?: boolean;
+}): {
+    difficulty: "random" | "count";
+    contrastCount: number;
+    composition: WordComposition;
+    /** @deprecated composition.cho 사용 — 세션 로그 호환용 */
+    choseong: string | null;
+    excludeNoImage: boolean;
+    sameStructureOnly: boolean;
+    gradeFilter: string[];
+    /** 품사 필터(라벨 배열) — caps.partOfSpeech일 때만 의미 있음 */
+    posFilter: string[];
+    /** 어종 필터(라벨 배열) — caps.wordType일 때만 의미 있음 */
+    wordTypeFilter: string[];
+    /** 현재 품사/어종 필터로 이 단어가 통과하는지 — 호출부가 자신의 후보 단어 목록에 적용 */
+    matchesWordAttributes: (entry: {
+        pos?: string;
+        wordType?: string;
+    }) => boolean;
+    poolVersion: number;
+    filterSections: FilterPanelSection[];
+    filterSelected: Record<string, string | string[]>;
+    handleFilterSelect: (value: string, sectionLabel: string) => void;
+    /** 훈련 음소 그룹 보기 모드 (글자/발음) + 전환(선택 매핑 포함) */
+    phonemeView: "char" | "pron" | "direct";
+    setPhonemeView: (next: "char" | "pron" | "direct") => void;
+    /** 훈련 음소 그룹 헤더 라벨 — groupAction(토글) 주입 대상 식별용 */
+    phonemeGroupLabel: string;
+    /** 현재 필터 조건으로 가능한 정답 단어 수 (null = 계산 전) */
+    wordCount: number | null;
+    /** 설정 팝업 취소용 — 스냅샷 캡처/복원 */
+    getFilterSnapshot: () => WordFilterSnapshot;
+    restoreFilterSnapshot: (s: WordFilterSnapshot) => void;
+};