@ihabdevteam/core 0.37.0 → 0.39.0

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

@@ -1,128 +1,10 @@
-'use client';
-import { useCallback, useEffect, useRef, useState } from 'react';
-import { shuffle } from '../utils/array';
-export function useSoundCompassExam(speakers, { mode = 'playback', autoStart = false, onPlaySpeaker, onComplete, playMs = 1100, feedbackMs = 1500, } = {}) {
-    const [queue, setQueue] = useState([]);
-    const [index, setIndex] = useState(0);
-    const [phase, setPhase] = useState('idle');
-    const [activeId, setActiveId] = useState(null);
-    const [playedIds, setPlayedIds] = useState([]);
-    const [selectedId, setSelectedId] = useState(null);
-    const [score, setScore] = useState(0);
-    // updater 밖에서 최신 score를 읽기 위한 미러 — setState updater 안에서 onComplete를
-    // 호출하면(부수효과) StrictMode에서 updater가 2회 실행돼 완료 콜백(점수 기록)이 중복된다.
-    const scoreRef = useRef(0);
-    const setScoreTracked = useCallback((next) => {
-        scoreRef.current = typeof next === 'function' ? next(scoreRef.current) : next;
-        setScore(scoreRef.current);
-    }, []);
-    // 최신 콜백/타이머 참조 (effect 재실행 없이 사용)
-    const onPlayRef = useRef(onPlaySpeaker);
-    const onDoneRef = useRef(onComplete);
-    useEffect(() => { onPlayRef.current = onPlaySpeaker; onDoneRef.current = onComplete; }, [onPlaySpeaker, onComplete]);
-    const timers = useRef([]);
-    const clearTimers = () => { timers.current.forEach(clearTimeout); timers.current = []; };
-    const after = (ms, fn) => { timers.current.push(setTimeout(fn, ms)); };
-    useEffect(() => () => clearTimers(), []);
-    const answerId = queue[index]?.id ?? null;
-    // ── playback: 모든 스피커를 순서대로 ──────────────────────────────────
-    const runPlayback = useCallback(() => {
-        clearTimers();
-        setPhase('playing');
-        setPlayedIds([]);
-        setSelectedId(null);
-        setScoreTracked(0);
-        let acc = 0;
-        speakers.forEach((sp, i) => {
-            after(acc, () => { setIndex(i); setActiveId(sp.id); onPlayRef.current?.(sp); });
-            after(acc + 1000, () => { setActiveId(null); setPlayedIds(prev => [...prev, sp.id]); });
-            acc += 1300;
-        });
-        after(acc, () => { setPhase('done'); onDoneRef.current?.({ score: 0, total: speakers.length }); });
-    }, [speakers, setScoreTracked]);
-    // ── practice / exam: 문제 재생 → 선택 대기 ────────────────────────────
-    const playQuestion = useCallback((q, i) => {
-        if (i >= q.length) {
-            setPhase('done');
-            onDoneRef.current?.({ score: scoreRef.current, total: q.length });
-            return;
-        }
-        setIndex(i);
-        setSelectedId(null);
-        setPhase('playing');
-        setActiveId(q[i].id);
-        onPlayRef.current?.(q[i]);
-        after(playMs, () => { setActiveId(null); setPhase('waiting'); });
-    }, [playMs]);
-    const runExam = useCallback(() => {
-        clearTimers();
-        const q = shuffle(speakers);
-        setQueue(q);
-        setScoreTracked(0);
-        setPlayedIds([]);
-        playQuestion(q, 0);
-    }, [speakers, playQuestion, setScoreTracked]);
-    const start = useCallback(() => {
-        if (mode === 'playback') {
-            setQueue(speakers);
-            runPlayback();
-        }
-        else
-            runExam();
-    }, [mode, speakers, runPlayback, runExam]);
-    const reset = useCallback(() => {
-        clearTimers();
-        setPhase('idle');
-        setActiveId(null);
-        setPlayedIds([]);
-        setSelectedId(null);
-        setIndex(0);
-        setScoreTracked(0);
-        setQueue([]);
-    }, [setScoreTracked]);
-    // autoStart / 입력 변경 시 재시작 — start/reset이 여러 상태를 동기 초기화하지만 의도된 동작이다
-    /* eslint-disable react-hooks/set-state-in-effect */
-    useEffect(() => {
-        if (autoStart)
-            start();
-        else
-            reset();
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [mode, speakers.length, autoStart]);
-    /* eslint-enable react-hooks/set-state-in-effect */
-    const onSelectSpeaker = useCallback((id) => {
-        if (phase !== 'waiting' || mode === 'playback')
-            return;
-        setSelectedId(id);
-        const correct = id === queue[index]?.id;
-        if (correct)
-            setScoreTracked(s => s + 1);
-        if (mode === 'exam') {
-            setPhase('playing');
-            after(400, () => playQuestion(queue, index + 1));
-        }
-        else {
-            setPhase('feedback');
-            after(feedbackMs, () => playQuestion(queue, index + 1));
-        }
-    }, [phase, mode, queue, index, playQuestion, feedbackMs, setScoreTracked]);
-    const total = mode === 'playback' ? speakers.length : queue.length;
-    return {
-        bind: {
-            activeSpeakerId: activeId,
-            playedIds,
-            selectedId,
-            answerId,
-            showFeedback: phase === 'feedback',
-            clickable: phase === 'waiting',
-            onSelectSpeaker,
-        },
-        index,
-        total,
-        score,
-        phase,
-        done: phase === 'done',
-        start,
-        reset,
-    };
-}
+/**
+ * 옛 자리 — 실제 몸은 `hooks/useSoundCompassExam.ts` 에 있다.
+ *
+ * 이것은 **머리 없는 오케스트레이터**다. `SoundCompass` 는 시키는 대로 그리기만 하고
+ * 순서·타이밍·점수·진행은 이 훅이 진다(SoundCompass.md 에 그렇게 적혀 있다).
+ * 코어의 어느 컴포넌트도 이것을 쓰지 않는다 — 소비자가 쓴다. 그러니 컴포넌트 곁이
+ * 아니라 `hooks/` 가 제자리다. 소리방향성이
+ * `@ihabdevteam/core/components/useSoundCompassExam` 로 가져가고 있어 이 자리를 남긴다.
+ */
+export { useSoundCompassExam } from '../hooks/useSoundCompassExam';

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

@@ -63,8 +63,8 @@ export { default as PassCardBgLeftColorGrid, passCardBgLeftColorGridTheme } from
 export type { PassCardBgLeftColorGridProps } from './components/PassCard/PassCardBgLeftColorGrid';
 export { default as SoundCompass } from './components/SoundCompass';
 export type { SoundCompassProps, SpeakerState } from './components/SoundCompass';
-export { useSoundCompassExam } from './components/useSoundCompassExam';
-export type { SoundCompassMode, SoundCompassPhase, SoundCompassExam, UseSoundCompassExamOptions } from './components/useSoundCompassExam';
+export { useSoundCompassExam } from './hooks/useSoundCompassExam';
+export type { SoundCompassMode, SoundCompassPhase, SoundCompassExam, UseSoundCompassExamOptions } from './hooks/useSoundCompassExam';
 export type { SpeakerPos } from './types/audio';
 export { default as SideNav } from './components/SideNav';
 export { default as Button } from './components/Button';
@@ -126,8 +126,8 @@ export type { TextFieldProps } from './components/TextField';
 export { useComboboxSuggestions } from './components/useComboboxSuggestions';
 export { default as Dropdown } from './components/Dropdown';
 export type { DropdownProps, DropdownOption } from './components/Dropdown';
-export { useAnchoredMenu } from './components/useAnchoredMenu';
-export type { UseAnchoredMenuOptions, UseAnchoredMenuResult } from './components/useAnchoredMenu';
+export { useAnchoredMenu } from './hooks/useAnchoredMenu';
+export type { UseAnchoredMenuOptions, UseAnchoredMenuResult } from './hooks/useAnchoredMenu';
 export { default as Toggle } from './components/Toggle';
 export type { ToggleProps } from './components/Toggle';
 export { default as Checkbox } from './components/Checkbox';

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

@@ -49,7 +49,7 @@ export { default as PassCardBgTwoCircle, passCardBgTwoCircleTheme } from './comp
 export { default as PassCardBgIHAB, passCardBgIhabTheme } from './components/PassCard/PassCardBgIHAB';
 export { default as PassCardBgLeftColorGrid, passCardBgLeftColorGridTheme } from './components/PassCard/PassCardBgLeftColorGrid';
 export { default as SoundCompass } from './components/SoundCompass';
-export { useSoundCompassExam } from './components/useSoundCompassExam';
+export { useSoundCompassExam } from './hooks/useSoundCompassExam';
 export { default as SideNav } from './components/SideNav';
 export { default as Button } from './components/Button';
 export { default as Badge } from './components/Badge';
@@ -83,7 +83,7 @@ export { default as SegmentedControl } from './components/SegmentedControl';
 export { default as TextField } from './components/TextField';
 export { useComboboxSuggestions } from './components/useComboboxSuggestions';
 export { default as Dropdown } from './components/Dropdown';
-export { useAnchoredMenu } from './components/useAnchoredMenu';
+export { useAnchoredMenu } from './hooks/useAnchoredMenu';
 export { default as Toggle } from './components/Toggle';
 export { default as Checkbox } from './components/Checkbox';
 export { default as BulkBar } from './components/BulkBar';

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

@@ -0,0 +1,28 @@
+import { type CSSProperties, type RefObject } from 'react';
+export interface UseAnchoredMenuOptions {
+    /** 트리거의 getBoundingClientRect()로부터 메뉴에 적용할 style을 계산 */
+    computeStyle: (triggerRect: DOMRect) => CSSProperties;
+    /** 열려있는 동안 스크롤 발생 시 동작 (메뉴 내부 스크롤은 항상 무시) — 기본 'close' */
+    onScroll?: 'close' | 'reposition' | 'ignore';
+    /** 열려있는 동안 윈도우 리사이즈 발생 시 동작 — 기본 'close' */
+    onResize?: 'close' | 'reposition' | 'ignore';
+    /** 바깥클릭 판정에서 제외할 CSS selector (예: 메뉴 안에 중첩 포탈되는 다른 드롭다운) */
+    ignoreOutsideClickSelector?: string;
+}
+export interface UseAnchoredMenuResult<Trigger extends HTMLElement, Menu extends HTMLElement> {
+    open: boolean;
+    setOpen: (open: boolean) => void;
+    toggle: () => void;
+    close: () => void;
+    /** 트리거 기준으로 계산된 메뉴 style — position:'fixed' 등은 computeStyle이 직접 반환 */
+    style: CSSProperties;
+    triggerRef: RefObject<Trigger | null>;
+    menuRef: RefObject<Menu | null>;
+}
+/**
+ * 트리거 요소에 fixed 포지션으로 앵커링되는 메뉴/드롭다운/팝오버의 공용 로직.
+ * 열림상태 + 위치 계산 + 바깥클릭/스크롤/리사이즈 처리를 담당하고, 렌더링(포탈 등)은
+ * 사용하는 쪽에서 담당한다. Dropdown, DatePicker, BottomNav의 "더보기" 메뉴가 이 훅을 쓴다.
+ * @public
+ */
+export declare function useAnchoredMenu<Trigger extends HTMLElement = HTMLElement, Menu extends HTMLElement = HTMLElement>({ computeStyle, onScroll, onResize, ignoreOutsideClickSelector, }: UseAnchoredMenuOptions): UseAnchoredMenuResult<Trigger, Menu>;

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

@@ -0,0 +1,72 @@
+'use client';
+import { useCallback, useEffect, useRef, useState } from 'react';
+/**
+ * 트리거 요소에 fixed 포지션으로 앵커링되는 메뉴/드롭다운/팝오버의 공용 로직.
+ * 열림상태 + 위치 계산 + 바깥클릭/스크롤/리사이즈 처리를 담당하고, 렌더링(포탈 등)은
+ * 사용하는 쪽에서 담당한다. Dropdown, DatePicker, BottomNav의 "더보기" 메뉴가 이 훅을 쓴다.
+ * @public
+ */
+export function useAnchoredMenu({ computeStyle, onScroll = 'close', onResize = 'close', ignoreOutsideClickSelector, }) {
+    const [open, setOpen] = useState(false);
+    const [style, setStyle] = useState({});
+    const triggerRef = useRef(null);
+    const menuRef = useRef(null);
+    const recalc = useCallback(() => {
+        if (!triggerRef.current)
+            return;
+        setStyle(computeStyle(triggerRef.current.getBoundingClientRect()));
+    }, [computeStyle]);
+    useEffect(() => {
+        if (!open)
+            return;
+        recalc();
+        const handleOutsideClick = (e) => {
+            const target = e.target;
+            if (ignoreOutsideClickSelector && target.closest?.(ignoreOutsideClickSelector))
+                return;
+            if (triggerRef.current?.contains(target))
+                return;
+            if (menuRef.current?.contains(target))
+                return;
+            setOpen(false);
+        };
+        document.addEventListener('mousedown', handleOutsideClick);
+        const handleScroll = (e) => {
+            if (menuRef.current?.contains(e.target))
+                return;
+            if (onScroll === 'reposition')
+                recalc();
+            else if (onScroll === 'close')
+                setOpen(false);
+        };
+        if (onScroll !== 'ignore')
+            window.addEventListener('scroll', handleScroll, true);
+        const handleResize = () => {
+            if (onResize === 'reposition')
+                recalc();
+            else if (onResize === 'close')
+                setOpen(false);
+        };
+        if (onResize !== 'ignore')
+            window.addEventListener('resize', handleResize);
+        // ESC로 닫기 — 이 훅을 쓰는 컴포넌트가 자체 키보드 핸들링(예: Dropdown의 화살표 탐색)을
+        // 따로 두더라도 무해하게 중복 호출될 뿐이므로, 여기서 공통으로 처리해 DatePicker/BottomNav
+        // 더보기 메뉴처럼 자체 ESC 처리가 없던 소비자도 함께 혜택을 받게 한다.
+        const handleKeyDown = (e) => {
+            if (e.key === 'Escape')
+                setOpen(false);
+        };
+        document.addEventListener('keydown', handleKeyDown);
+        return () => {
+            document.removeEventListener('mousedown', handleOutsideClick);
+            if (onScroll !== 'ignore')
+                window.removeEventListener('scroll', handleScroll, true);
+            if (onResize !== 'ignore')
+                window.removeEventListener('resize', handleResize);
+            document.removeEventListener('keydown', handleKeyDown);
+        };
+    }, [open, recalc, onScroll, onResize, ignoreOutsideClickSelector]);
+    const toggle = useCallback(() => setOpen(o => !o), []);
+    const close = useCallback(() => setOpen(false), []);
+    return { open, setOpen, toggle, close, style, triggerRef, menuRef };
+}

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

@@ -0,0 +1,54 @@
+import type { SpeakerPos } from '../types/audio';
+/**
+ * @public
+ * SoundCompass 오케스트레이션 참조 훅.
+ *
+ * SoundCompass 자체는 제어형(표현) 컴포넌트라 순서·타이밍·점수·진행을 갖지 않는다.
+ * 이 훅이 그 "부모(검사 컨트롤러)" 역할의 기본 구현을 제공한다 —
+ * 큐 셔플, 문제 재생 타이밍, 선택 수집, 피드백, 진행/점수, 완료 콜백.
+ *
+ * 반환한 `bind`를 `<SoundCompass {...exam.bind} />`처럼 펼쳐 넣으면 된다.
+ * 다른 동작이 필요하면 이 훅을 복사·수정하거나, SoundCompass의 제어 props를
+ * 직접 구동해도 된다.
+ */
+export type SoundCompassMode = 'playback' | 'practice' | 'exam';
+export interface UseSoundCompassExamOptions {
+    /** 동작 모드. 기본 'playback' */
+    mode?: SoundCompassMode;
+    /** 마운트/리셋 시 자동 시작. 기본 false */
+    autoStart?: boolean;
+    /** 스피커 소리를 재생해야 할 때 호출 (오디오는 호출자 담당) */
+    onPlaySpeaker?: (speaker: SpeakerPos) => void;
+    /** 모든 문제/재생 완료 시 호출 */
+    onComplete?: (result: {
+        score: number;
+        total: number;
+    }) => void;
+    /** 문제당 소리 재생 후 선택 대기까지 지연(ms). 기본 1100 */
+    playMs?: number;
+    /** practice 모드 피드백 표시 시간(ms). 기본 1500 */
+    feedbackMs?: number;
+}
+export type SoundCompassPhase = 'idle' | 'playing' | 'waiting' | 'feedback' | 'done';
+export interface SoundCompassExam {
+    /** `<SoundCompass {...bind} />` 로 펼쳐 넣는 제어 props */
+    bind: {
+        activeSpeakerId: string | null;
+        playedIds: string[];
+        selectedId: string | null;
+        answerId: string | null;
+        showFeedback: boolean;
+        clickable: boolean;
+        onSelectSpeaker: (id: string) => void;
+    };
+    index: number;
+    total: number;
+    score: number;
+    phase: SoundCompassPhase;
+    done: boolean;
+    /** 시작(또는 재시작) */
+    start: () => void;
+    /** idle 상태로 리셋 */
+    reset: () => void;
+}
+export declare function useSoundCompassExam(speakers: SpeakerPos[], { mode, autoStart, onPlaySpeaker, onComplete, playMs, feedbackMs, }?: UseSoundCompassExamOptions): SoundCompassExam;

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

@@ -0,0 +1,128 @@
+'use client';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { shuffle } from '../utils/array';
+export function useSoundCompassExam(speakers, { mode = 'playback', autoStart = false, onPlaySpeaker, onComplete, playMs = 1100, feedbackMs = 1500, } = {}) {
+    const [queue, setQueue] = useState([]);
+    const [index, setIndex] = useState(0);
+    const [phase, setPhase] = useState('idle');
+    const [activeId, setActiveId] = useState(null);
+    const [playedIds, setPlayedIds] = useState([]);
+    const [selectedId, setSelectedId] = useState(null);
+    const [score, setScore] = useState(0);
+    // updater 밖에서 최신 score를 읽기 위한 미러 — setState updater 안에서 onComplete를
+    // 호출하면(부수효과) StrictMode에서 updater가 2회 실행돼 완료 콜백(점수 기록)이 중복된다.
+    const scoreRef = useRef(0);
+    const setScoreTracked = useCallback((next) => {
+        scoreRef.current = typeof next === 'function' ? next(scoreRef.current) : next;
+        setScore(scoreRef.current);
+    }, []);
+    // 최신 콜백/타이머 참조 (effect 재실행 없이 사용)
+    const onPlayRef = useRef(onPlaySpeaker);
+    const onDoneRef = useRef(onComplete);
+    useEffect(() => { onPlayRef.current = onPlaySpeaker; onDoneRef.current = onComplete; }, [onPlaySpeaker, onComplete]);
+    const timers = useRef([]);
+    const clearTimers = () => { timers.current.forEach(clearTimeout); timers.current = []; };
+    const after = (ms, fn) => { timers.current.push(setTimeout(fn, ms)); };
+    useEffect(() => () => clearTimers(), []);
+    const answerId = queue[index]?.id ?? null;
+    // ── playback: 모든 스피커를 순서대로 ──────────────────────────────────
+    const runPlayback = useCallback(() => {
+        clearTimers();
+        setPhase('playing');
+        setPlayedIds([]);
+        setSelectedId(null);
+        setScoreTracked(0);
+        let acc = 0;
+        speakers.forEach((sp, i) => {
+            after(acc, () => { setIndex(i); setActiveId(sp.id); onPlayRef.current?.(sp); });
+            after(acc + 1000, () => { setActiveId(null); setPlayedIds(prev => [...prev, sp.id]); });
+            acc += 1300;
+        });
+        after(acc, () => { setPhase('done'); onDoneRef.current?.({ score: 0, total: speakers.length }); });
+    }, [speakers, setScoreTracked]);
+    // ── practice / exam: 문제 재생 → 선택 대기 ────────────────────────────
+    const playQuestion = useCallback((q, i) => {
+        if (i >= q.length) {
+            setPhase('done');
+            onDoneRef.current?.({ score: scoreRef.current, total: q.length });
+            return;
+        }
+        setIndex(i);
+        setSelectedId(null);
+        setPhase('playing');
+        setActiveId(q[i].id);
+        onPlayRef.current?.(q[i]);
+        after(playMs, () => { setActiveId(null); setPhase('waiting'); });
+    }, [playMs]);
+    const runExam = useCallback(() => {
+        clearTimers();
+        const q = shuffle(speakers);
+        setQueue(q);
+        setScoreTracked(0);
+        setPlayedIds([]);
+        playQuestion(q, 0);
+    }, [speakers, playQuestion, setScoreTracked]);
+    const start = useCallback(() => {
+        if (mode === 'playback') {
+            setQueue(speakers);
+            runPlayback();
+        }
+        else
+            runExam();
+    }, [mode, speakers, runPlayback, runExam]);
+    const reset = useCallback(() => {
+        clearTimers();
+        setPhase('idle');
+        setActiveId(null);
+        setPlayedIds([]);
+        setSelectedId(null);
+        setIndex(0);
+        setScoreTracked(0);
+        setQueue([]);
+    }, [setScoreTracked]);
+    // autoStart / 입력 변경 시 재시작 — start/reset이 여러 상태를 동기 초기화하지만 의도된 동작이다
+    /* eslint-disable react-hooks/set-state-in-effect */
+    useEffect(() => {
+        if (autoStart)
+            start();
+        else
+            reset();
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [mode, speakers.length, autoStart]);
+    /* eslint-enable react-hooks/set-state-in-effect */
+    const onSelectSpeaker = useCallback((id) => {
+        if (phase !== 'waiting' || mode === 'playback')
+            return;
+        setSelectedId(id);
+        const correct = id === queue[index]?.id;
+        if (correct)
+            setScoreTracked(s => s + 1);
+        if (mode === 'exam') {
+            setPhase('playing');
+            after(400, () => playQuestion(queue, index + 1));
+        }
+        else {
+            setPhase('feedback');
+            after(feedbackMs, () => playQuestion(queue, index + 1));
+        }
+    }, [phase, mode, queue, index, playQuestion, feedbackMs, setScoreTracked]);
+    const total = mode === 'playback' ? speakers.length : queue.length;
+    return {
+        bind: {
+            activeSpeakerId: activeId,
+            playedIds,
+            selectedId,
+            answerId,
+            showFeedback: phase === 'feedback',
+            clickable: phase === 'waiting',
+            onSelectSpeaker,
+        },
+        index,
+        total,
+        score,
+        phase,
+        done: phase === 'done',
+        start,
+        reset,
+    };
+}

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

@@ -26,6 +26,7 @@ export declare function useWordAttributeFilterKeys(): WordAttributeFilterKeys;
 export declare function buildGradeSection(t: TFunction, keys: WordAttributeFilterKeys, opts?: {
     allLabel?: string;
     labelAction?: ReactNode;
+    labelInfo?: FilterPanelSection['labelInfo'];
 }): FilterPanelSection;
 /** @public 품사 FilterPanelSection — 세 화면 공용. */
 export declare function buildPartOfSpeechSection(keys: WordAttributeFilterKeys): FilterPanelSection;
@@ -42,6 +43,7 @@ export declare function buildSyllableSection(t: TFunction, keys: WordAttributeFi
 export declare function buildSelectSection(t: TFunction, opts?: {
     includeStructure?: boolean;
     labelAction?: ReactNode;
+    labelInfo?: FilterPanelSection['labelInfo'];
 }): FilterPanelSection;
 /**
  * @public 위치(어두/어중/어말) FilterPanelSection 빌더 — WordSearchPage·단어훈련 만들기(메인 앱)가 공용.

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

@@ -37,6 +37,7 @@ export function buildGradeSection(t, keys, opts) {
         allOption: true,
         allLabel: opts?.allLabel,
         labelAction: opts?.labelAction,
+        labelInfo: opts?.labelInfo,
     };
 }
 /** @public 품사 FilterPanelSection — 세 화면 공용. */
@@ -72,7 +73,7 @@ export function buildSelectSection(t, opts) {
     const items = [t('wordPairs.filter.onlyHasImage', '이미지 있는 단어만')];
     if (opts?.includeStructure)
         items.push(t('wordPairs.filter.onlySameStructure', '음소 구조 같은 단어만'));
-    return { label: t('wordPairs.filter.selectLabel', '선택'), items, multiple: true, labelAction: opts?.labelAction };
+    return { label: t('wordPairs.filter.selectLabel', '선택'), items, multiple: true, labelAction: opts?.labelAction, labelInfo: opts?.labelInfo };
 }
 /**
  * @public 위치(어두/어중/어말) FilterPanelSection 빌더 — WordSearchPage·단어훈련 만들기(메인 앱)가 공용.

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

@@ -1,13 +1,8 @@
 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;
-}
+import type { WordTrainingType } from '../utils/wordTrainingRuntimeTypes';
+export type { WordTrainingType } from '../utils/wordTrainingRuntimeTypes';
 interface WordTrainingDataEntry {
     id: string;
     name: string;
@@ -31,4 +26,3 @@ export declare function useWordTrainingDataGeneration(types: WordTrainingType[],
     perTypeData: Record<string, WordTrainingDataEntry | null>;
     generating: boolean;
 };
-export {};

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

@@ -1,10 +1,9 @@
 'use client';
-import { useCallback, useEffect, useMemo, useRef, useState, createElement } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } 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';
@@ -327,7 +326,9 @@ export function useWordTrainingFilter(groupKey, caps, opts) {
     const partByLabel = useMemo(() => ({
         [LABELS.trainOnset]: 'cho', [LABELS.trainVowel]: 'jung', [LABELS.trainCoda]: 'jong',
     }), [LABELS]);
-    const infoAction = useCallback((items, title) => createElement(FilterSectionInfo, { title, items }), []);
+    /* 요소가 아니라 **서술**을 넘긴다 — 그리는 일은 FilterPanel 이 한다.
+       예전에는 여기서 createElement 로 만들었고, 그 탓에 훅이 컴포넌트를 올려다봤다. */
+    const infoAction = useCallback((items, title) => ({ title, items }), []);
     const selectInfoItems = useMemo(() => [
         t('training.filter.excludeImageInfo', { defaultValue: '이미지 있는 단어만: 단어 중에 이미지가 있는 단어만 결과에 보여줍니다.' }),
         t('training.filter.sameStructureInfo', { defaultValue: '음소 구조 같은 단어만: 정답과 오답의 음절 구조(글자 수·받침 유무 등)가 같은 결과만 남겨요.' }),
@@ -383,7 +384,7 @@ export function useWordTrainingFilter(groupKey, caps, opts) {
         // label만 오버라이드하고 나머지(items/allOption 등)는 공용 빌더 그대로 사용.
         sections.push({
             ...buildGradeSection(t, attrKeys, {
-                labelAction: infoAction([t('wordPairs.filter.difficultyInfo', { defaultValue: '국립국어원의 기초 어휘 등급이 결과에 반영됩니다.' })]),
+                labelInfo: infoAction([t('wordPairs.filter.difficultyInfo', { defaultValue: '국립국어원의 기초 어휘 등급이 결과에 반영됩니다.' })]),
             }),
             label: LABELS.gradeLabel,
         });
@@ -423,10 +424,10 @@ export function useWordTrainingFilter(groupKey, caps, opts) {
         // 선택 — choseong 타입은 긍정형 다중 토글(이미지 있는 단어만 / 음소 구조 같은 단어만),
         // 아니면 이미지 제외만 마지막에 노출. (받침 제외는 종성 섹션의 '제외' 버튼)
         if (caps.choseong) {
-            sections.push({ label: LABELS.exclude, displayLabel: LABELS.selectLabel, multiple: true, items: [LABELS.excludeImage, LABELS.sameStructure], labelAction: infoAction(selectInfoItems) });
+            sections.push({ label: LABELS.exclude, displayLabel: LABELS.selectLabel, multiple: true, items: [LABELS.excludeImage, LABELS.sameStructure], labelInfo: infoAction(selectInfoItems) });
         }
         else {
-            sections.push({ label: LABELS.exclude, displayLabel: LABELS.selectLabel, multiple: true, items: [LABELS.excludeImage], labelAction: infoAction([selectInfoItems[0]]) });
+            sections.push({ label: LABELS.exclude, displayLabel: LABELS.selectLabel, multiple: true, items: [LABELS.excludeImage], labelInfo: 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]);

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

@@ -26,3 +26,7 @@ export * from './hooks/usePagedList';
 export * from './hooks/useToastState';
 export { useTrainingTypeLabels } from './hooks/useTrainingTypeLabels';
 export { CORE_VERSION } from './version';
+export { useAnchoredMenu } from './hooks/useAnchoredMenu';
+export type { UseAnchoredMenuOptions, UseAnchoredMenuResult } from './hooks/useAnchoredMenu';
+export { useSoundCompassExam } from './hooks/useSoundCompassExam';
+export type { SoundCompassMode, SoundCompassPhase, SoundCompassExam, UseSoundCompassExamOptions } from './hooks/useSoundCompassExam';

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

@@ -27,3 +27,9 @@ export * from './hooks/usePagedList';
 export * from './hooks/useToastState';
 export { useTrainingTypeLabels } from './hooks/useTrainingTypeLabels';
 export { CORE_VERSION } from './version';
+/* 컴포넌트 곁에 있다가 이리로 온 둘 — 옛 경로(`components/…`)도 껍데기로 살아 있다.
+   기준은 "몇 곳이 쓰는가" 다: useAnchoredMenu 는 네 컴포넌트가 함께 쓰고,
+   useSoundCompassExam 은 어느 컴포넌트도 안 쓴다(소비자가 쓰는 머리 없는 훅이다).
+   한 컴포넌트만 쓰는 훅 다섯은 그 곁에 그대로 두었다 — 옮기면 응집만 떨어진다. */
+export { useAnchoredMenu } from './hooks/useAnchoredMenu';
+export { useSoundCompassExam } from './hooks/useSoundCompassExam';

package/dist/packages/core/src/i18n/locales/en.json

@@ -2571,6 +2571,14 @@
         "orDivider": "or",
         "kakaoStart": "Continue with Kakao"
     },
+    "kakaoLink": {
+        "title": "Kakao login linked",
+        "messageWithEmail": "Kakao login was added to {{email}}. You can now sign in either way.",
+        "message": "Kakao login was added to your existing account with the same email. You can now sign in either way.",
+        "keep": "OK",
+        "unlink": "Unlink",
+        "unlinkFailed": "Could not unlink."
+    },
     "agreementGate": {
         "title": "Agreement required",
         "subtitle": "Please agree to the Terms of Use and Privacy Policy to continue using the service.",

package/dist/packages/core/src/i18n/locales/ko.json

@@ -2569,6 +2569,14 @@
         "orDivider": "또는",
         "kakaoStart": "카카오로 시작하기"
     },
+    "kakaoLink": {
+        "title": "카카오 로그인이 연결되었습니다",
+        "messageWithEmail": "{{email}} 계정에 카카오 로그인이 추가되었습니다. 이제 두 가지 방법으로 모두 로그인할 수 있습니다.",
+        "message": "같은 이메일로 가입된 기존 계정에 카카오 로그인이 추가되었습니다. 이제 두 가지 방법으로 모두 로그인할 수 있습니다.",
+        "keep": "확인",
+        "unlink": "연결 해제",
+        "unlinkFailed": "연결을 해제하지 못했습니다."
+    },
     "agreementGate": {
         "title": "약관 동의가 필요합니다",
         "subtitle": "서비스를 계속 이용하시려면 이용약관과 개인정보처리방침에 동의해 주세요.",

package/dist/packages/core/src/types/filterPanel.d.ts

@@ -45,6 +45,21 @@ export interface FilterPanelSection {
     /** 가로 배치에서 이 섹션을 한 줄 전체(자체 줄)로 배치 — 인라인 흐름에서 분리 */
     block?: boolean;
     labelAction?: ReactNode;
+    /**
+     * 라벨 옆 "?" 설명 버튼을 **서술로** 지정한다 — `labelAction` 에 요소를 직접 넣는 대신
+     * 내용만 준다. FilterPanel 이 `FilterSectionInfo` 로 그린다.
+     *
+     * 왜 두 갈래인가: 훅은 화면을 그리면 안 된다. 섹션을 만들어 주는 훅
+     * (`useWordTrainingFilter`)이 예전에는 `createElement(FilterSectionInfo, …)` 로
+     * 요소를 만들었는데, 그러려면 **훅이 컴포넌트를 올려다봐야** 했다. 이 슬롯을 쓰면
+     * 훅은 내용만 넘기고 그리는 일은 컴포넌트가 한다.
+     * `labelAction` 은 그대로 둔다 — 호출부가 제 요소를 넣고 싶을 때가 있다.
+     * 둘 다 있으면 `labelAction` 이 이긴다.
+     */
+    labelInfo?: {
+        title?: string;
+        items: string[];
+    };
     items?: (FilterPanelItem | string)[];
     groups?: (FilterPanelItem | string)[][];
     /** 'note': 선택 불가능한 안내 텍스트 섹션 — content를 그대로 렌더링한다(예: 입력 구문 사용법). */