@ihabdevteam/core 0.8.0

package/dist/packages/core/src/components/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/components/useBarChartControl.d.ts

@@ -0,0 +1,8 @@
+import type { MonthBarData } from './barChartData';
+import type { BarChartControl } from './barChartTypes';
+/**
+ * BarChart 기간 상태/옵션/네비게이션을 캡슐화한 훅.
+ * 여러 BarChart가 하나의 컨트롤을 공유하려면 이 훅을 상위에서 호출해 control을 내려준다.
+ * @public
+ */
+export declare function useBarChartControl(data: Record<string, MonthBarData>): BarChartControl;

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

@@ -0,0 +1,76 @@
+'use client';
+import { useState, useEffect, useMemo, useCallback } from 'react';
+import { useTranslation } from 'react-i18next';
+import { firstMondayOfMonth, todayWeekValue, MONTH_OPTIONS, KO_ORD } from './barChartData';
+/**
+ * BarChart 기간 상태/옵션/네비게이션을 캡슐화한 훅.
+ * 여러 BarChart가 하나의 컨트롤을 공유하려면 이 훅을 상위에서 호출해 control을 내려준다.
+ * @public
+ */
+export function useBarChartControl(data) {
+    const { t, i18n } = useTranslation();
+    const [period, setPeriod] = useState('week');
+    const DATA_MONTH_OPTIONS = useMemo(() => MONTH_OPTIONS.filter(o => o.value in data), [data]);
+    const WEEK_OPTIONS = useMemo(() => {
+        const opts = [];
+        for (const o of DATA_MONTH_OPTIONS) {
+            const daysInMonth = new Date(o.year, o.month, 0).getDate();
+            const firstMon = firstMondayOfMonth(o.year, o.month - 1);
+            const numWeeks = Math.ceil((daysInMonth - firstMon + 1) / 7);
+            for (let w = numWeeks - 1; w >= 0; w--) {
+                opts.push({ value: `${o.value}#${w}`, monthKey: o.value, year: o.year, month: o.month, week: w });
+            }
+        }
+        return opts;
+    }, [DATA_MONTH_OPTIONS]);
+    const weekOptionLabel = useCallback((o) => {
+        const m = t('calendar.yearMonth', { year: o.year, month: o.month });
+        return i18n.language?.startsWith('ko')
+            ? `${m} ${KO_ORD[o.week] ?? `${o.week + 1}`}주`
+            : `${m} Week ${o.week + 1}`;
+    }, [t, i18n.language]);
+    const monthOptions = useMemo(() => DATA_MONTH_OPTIONS.map(o => ({
+        value: o.value, label: t('calendar.yearMonth', { year: o.year, month: o.month }),
+    })), [t, DATA_MONTH_OPTIONS]);
+    const weekOptions = useMemo(() => WEEK_OPTIONS.map(o => ({ value: o.value, label: weekOptionLabel(o) })), [WEEK_OPTIONS, weekOptionLabel]);
+    // 진입 시 기본 선택을 오늘 기준으로 — 오늘이 속한 월/주(데이터에 있으면), 없으면 최신
+    const today = useMemo(() => todayWeekValue(), []);
+    const defaultMonth = useMemo(() => DATA_MONTH_OPTIONS.find(o => o.value === today.monthKey)?.value ?? DATA_MONTH_OPTIONS[0]?.value ?? '', [DATA_MONTH_OPTIONS, today]);
+    const defaultWeek = useMemo(() => WEEK_OPTIONS.find(o => o.value === today.value)?.value ?? WEEK_OPTIONS[0]?.value ?? '', [WEEK_OPTIONS, today]);
+    const [monthRange, setMonthRange] = useState('');
+    const [weekRange, setWeekRange] = useState('');
+    // 옵션 목록이 바뀌어 선택값이 무효해지면 기본값으로 보정하는 의도된 동기화다
+    /* eslint-disable react-hooks/set-state-in-effect */
+    useEffect(() => {
+        if (!DATA_MONTH_OPTIONS.find(o => o.value === monthRange))
+            setMonthRange(defaultMonth);
+    }, [DATA_MONTH_OPTIONS, monthRange, defaultMonth]);
+    useEffect(() => {
+        if (!WEEK_OPTIONS.find(o => o.value === weekRange))
+            setWeekRange(defaultWeek);
+    }, [WEEK_OPTIONS, weekRange, defaultWeek]);
+    /* eslint-enable react-hooks/set-state-in-effect */
+    const activeOptions = period === 'month' ? monthOptions : weekOptions;
+    const range = period === 'month' ? monthRange : weekRange;
+    const setRange = period === 'month' ? setMonthRange : setWeekRange;
+    const DOW = useMemo(() => {
+        const d = t('calendar.dow', { returnObjects: true });
+        return Array.isArray(d) ? d : ['일', '월', '화', '수', '목', '금', '토'];
+    }, [t]);
+    const activeIdx = activeOptions.findIndex(o => o.value === range);
+    const handlePrev = useCallback(() => {
+        const idx = activeOptions.findIndex(o => o.value === range);
+        if (idx < activeOptions.length - 1)
+            setRange(activeOptions[idx + 1].value);
+    }, [activeOptions, range, setRange]);
+    const handleNext = useCallback(() => {
+        const idx = activeOptions.findIndex(o => o.value === range);
+        if (idx > 0)
+            setRange(activeOptions[idx - 1].value);
+    }, [activeOptions, range, setRange]);
+    const periodOptions = useMemo(() => [
+        { key: 'week', label: t('manager.chart.periodWeek', '주') },
+        { key: 'month', label: t('manager.chart.periodMonth', '월') },
+    ], [t]);
+    return { period, setPeriod, range, setRange, activeOptions, activeIdx, handlePrev, handleNext, periodOptions, monthRange, weekRange, weekRanges: WEEK_OPTIONS, DOW };
+}

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

@@ -0,0 +1,12 @@
+export interface UseCalendarMonthResult {
+    viewY: number;
+    viewM: number;
+    prevMonth: () => void;
+    nextMonth: () => void;
+    setViewYM: (y: number, m: number) => void;
+}
+/**
+ * "현재 보고 있는 연/월" 상태 + 이전/다음 달 이동. DatePicker의 달력 네비게이션에서 쓴다.
+ * @public
+ */
+export declare function useCalendarMonth(value: string): UseCalendarMonthResult;

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

@@ -0,0 +1,50 @@
+'use client';
+import { useCallback, useEffect, useRef, useState } from 'react';
+/**
+ * "현재 보고 있는 연/월" 상태 + 이전/다음 달 이동. DatePicker의 달력 네비게이션에서 쓴다.
+ * @public
+ */
+export function useCalendarMonth(value) {
+    const initYM = () => {
+        if (value) {
+            const [y, m] = value.split('-');
+            return { y: +y, m: +m - 1 };
+        }
+        const today = new Date();
+        return { y: today.getFullYear(), m: today.getMonth() };
+    };
+    const [viewY, setViewY] = useState(() => initYM().y);
+    const [viewM, setViewM] = useState(() => initYM().m);
+    // value가 외부(부모)에서 바뀌면(예: 폼 리셋으로 선택값이 지워짐) 뷰도 그 달로 따라가야
+    // 한다 — 마운트 시 한 번만 초기값을 잡던 이전 구현은 이후 value 변경을 무시했다.
+    // 사용자가 prevMonth/nextMonth로 직접 탐색하는 로컬 동작은 value를 건드리지 않으므로
+    // 이 effect와 충돌하지 않는다.
+    const prevValueRef = useRef(value);
+    useEffect(() => {
+        if (value === prevValueRef.current)
+            return;
+        prevValueRef.current = value;
+        const next = initYM();
+        setViewY(next.y);
+        setViewM(next.m);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [value]);
+    const prevMonth = useCallback(() => {
+        if (viewM === 0) {
+            setViewY(y => y - 1);
+            setViewM(11);
+        }
+        else
+            setViewM(m => m - 1);
+    }, [viewM]);
+    const nextMonth = useCallback(() => {
+        if (viewM === 11) {
+            setViewY(y => y + 1);
+            setViewM(0);
+        }
+        else
+            setViewM(m => m + 1);
+    }, [viewM]);
+    const setViewYM = useCallback((y, m) => { setViewY(y); setViewM(m); }, []);
+    return { viewY, viewM, prevMonth, nextMonth, setViewYM };
+}

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

@@ -0,0 +1,22 @@
+import { type KeyboardEvent } from 'react';
+/**
+ * TextField의 `suggestions` 옵션이 쓰는 자동완성 콤보박스 상태/키보드 로직.
+ * 순수 입력(값 관리)과 분리해서, 자동완성이 필요 없는 TextField 사용처는
+ * 이 훅의 상태가 전혀 관여하지 않는다(항상 호출되지만 open은 기본 false로 시작).
+ * @public
+ */
+export declare function useComboboxSuggestions({ value, onChange, suggestions, openOnFocus, }: {
+    value: string;
+    onChange?: (value: string) => void;
+    suggestions: string[];
+    openOnFocus?: boolean;
+}): {
+    listId: string;
+    open: boolean;
+    activeIdx: number;
+    filtered: string[];
+    handleFocus: () => void;
+    handleBlur: () => void;
+    handleKeyDown: (e: KeyboardEvent<HTMLInputElement | HTMLTextAreaElement>) => void;
+    handleSelect: (item: string) => void;
+};

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

@@ -0,0 +1,60 @@
+'use client';
+import { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react';
+/**
+ * TextField의 `suggestions` 옵션이 쓰는 자동완성 콤보박스 상태/키보드 로직.
+ * 순수 입력(값 관리)과 분리해서, 자동완성이 필요 없는 TextField 사용처는
+ * 이 훅의 상태가 전혀 관여하지 않는다(항상 호출되지만 open은 기본 false로 시작).
+ * @public
+ */
+export function useComboboxSuggestions({ value, onChange, suggestions, openOnFocus = false, }) {
+    const listId = useId();
+    const [open, setOpen] = useState(false);
+    const [activeIdx, setActiveIdx] = useState(-1);
+    const blurTimerRef = useRef(null);
+    const filtered = useMemo(() => {
+        if (!suggestions.length)
+            return [];
+        const v = value ?? '';
+        if (!v)
+            return openOnFocus ? suggestions : [];
+        return suggestions.filter(s => s.toLowerCase().includes(v.toLowerCase()));
+    }, [suggestions, value, openOnFocus]);
+    // 메뉴가 닫히면 활성 인덱스를 리셋하는 의도된 동기화다
+    // eslint-disable-next-line react-hooks/set-state-in-effect
+    useEffect(() => { if (!open)
+        setActiveIdx(-1); }, [open]);
+    useEffect(() => () => { if (blurTimerRef.current)
+        clearTimeout(blurTimerRef.current); }, []);
+    const handleSelect = useCallback((item) => {
+        onChange?.(item);
+        setOpen(false);
+    }, [onChange]);
+    const handleFocus = useCallback(() => setOpen(true), []);
+    // blur가 리스트 항목의 onMouseDown보다 먼저 발생하는 걸 막기 위한 딜레이
+    const handleBlur = useCallback(() => {
+        blurTimerRef.current = setTimeout(() => setOpen(false), 120);
+    }, []);
+    const handleKeyDown = useCallback((e) => {
+        if (e.key === 'ArrowDown') {
+            e.preventDefault();
+            setOpen(true);
+            setActiveIdx(i => Math.min(filtered.length - 1, i + 1));
+        }
+        else if (e.key === 'ArrowUp') {
+            e.preventDefault();
+            setActiveIdx(i => Math.max(-1, i - 1));
+        }
+        else if (e.key === 'Enter') {
+            // 한글 조합을 끝내는 Enter는 선택이 아니다 — 조합 중엔 제안을 고르지 않는다
+            if (activeIdx >= 0 && !e.nativeEvent.isComposing)
+                handleSelect(filtered[activeIdx]);
+        }
+        else if (e.key === 'Escape') {
+            if (open) {
+                e.preventDefault();
+                setOpen(false);
+            } // 제안이 열렸을 때만 소비(상위 팝업 ESC보다 우선하지 않도록)
+        }
+    }, [filtered, activeIdx, open, handleSelect]);
+    return { listId, open, activeIdx, filtered, handleFocus, handleBlur, handleKeyDown, handleSelect };
+}

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

@@ -0,0 +1,16 @@
+import { type RefObject } from 'react';
+export interface UseFitScaleResult {
+    scalerRef: RefObject<HTMLDivElement | null>;
+    scale: number;
+    offset: number;
+}
+/**
+ * 고정 크기 콘텐츠(예: 인쇄용 용지)를 리사이즈 가능한 컨테이너에 맞춰 축소하고,
+ * 남는 가로 공간만큼 가운데 정렬 offset을 계산한다. WordTable이 용지 미리보기에 사용한다.
+ * - contentHeight 미지정: 컨테이너 '폭'에만 맞춘다(기존 동작 — 세로로는 넘치면 스크롤).
+ * - contentHeight 지정: 폭과 '높이'를 모두 만족하는 더 작은 배율로 맞춰 잘리지 않게 한다.
+ *   이때는 스케일러 자신(축소된 콘텐츠 높이)이 아니라 상위 컨테이너의 가용 영역을 재야 하므로
+ *   부모 요소를 측정한다(부모가 높이 제한된 박스여야 한다).
+ * @public
+ */
+export declare function useFitScale(contentWidth: number, contentHeight?: number): UseFitScaleResult;

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

@@ -0,0 +1,43 @@
+'use client';
+import { useCallback, useEffect, useRef, useState } from 'react';
+/**
+ * 고정 크기 콘텐츠(예: 인쇄용 용지)를 리사이즈 가능한 컨테이너에 맞춰 축소하고,
+ * 남는 가로 공간만큼 가운데 정렬 offset을 계산한다. WordTable이 용지 미리보기에 사용한다.
+ * - contentHeight 미지정: 컨테이너 '폭'에만 맞춘다(기존 동작 — 세로로는 넘치면 스크롤).
+ * - contentHeight 지정: 폭과 '높이'를 모두 만족하는 더 작은 배율로 맞춰 잘리지 않게 한다.
+ *   이때는 스케일러 자신(축소된 콘텐츠 높이)이 아니라 상위 컨테이너의 가용 영역을 재야 하므로
+ *   부모 요소를 측정한다(부모가 높이 제한된 박스여야 한다).
+ * @public
+ */
+export function useFitScale(contentWidth, contentHeight) {
+    const scalerRef = useRef(null);
+    const [scale, setScale] = useState(1);
+    const [offset, setOffset] = useState(0);
+    const updateScale = useCallback((containerWidth, containerHeight) => {
+        const sw = containerWidth / contentWidth;
+        const sh = contentHeight ? containerHeight / contentHeight : Infinity;
+        const s = Math.min(1, sw, sh);
+        setScale(s);
+        setOffset(Math.max(0, (containerWidth - contentWidth * s) / 2));
+    }, [contentWidth, contentHeight]);
+    useEffect(() => {
+        const el = scalerRef.current;
+        if (!el)
+            return;
+        // 높이까지 맞출 땐 부모(높이 제한 박스)를, 아니면 기존처럼 스케일러 자신을 관측한다.
+        const target = contentHeight ? (el.parentElement ?? el) : el;
+        // 측정은 반드시 '변환을 뺀' 레이아웃 크기를 써야 한다 — getBoundingClientRect는 조상 CSS
+        // transform(예: 저장 팝업 미리보기의 scale())까지 반영해 폭이 줄어든 값을 돌려주므로,
+        // 초기값은 clientWidth/Height, 이후는 ResizeObserver의 contentRect(둘 다 변환 무시)로 잰다.
+        updateScale(target.clientWidth, target.clientHeight);
+        // ResizeObserver 가 없는 환경(구형 브라우저·SSR·테스트 러너)에서는 생성자 호출이
+        // 그대로 던져 렌더가 통째로 깨진다. 위에서 초기값은 이미 쟀으므로 추적만 포기한다
+        // (Popup·CrosswordGame·Tooltip 과 같은 처리).
+        if (typeof ResizeObserver === 'undefined')
+            return;
+        const observer = new ResizeObserver(([entry]) => updateScale(entry.contentRect.width, entry.contentRect.height));
+        observer.observe(target);
+        return () => observer.disconnect();
+    }, [updateScale, contentHeight]);
+    return { scalerRef, scale, offset };
+}

package/dist/packages/core/src/components/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/components/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/components/useToastLifecycle.d.ts

@@ -0,0 +1,16 @@
+export interface UseToastLifecycleOptions {
+    message: string;
+    position: 'top' | 'bottom';
+    duration: number;
+    onClose: () => void;
+}
+export interface UseToastLifecycleResult {
+    mounted: boolean;
+    showing: boolean;
+    popupRef: React.RefObject<HTMLDivElement | null>;
+}
+/**
+ * Toast의 등장/퇴장 슬라이드 애니메이션 + 자동 닫힘 타이머 상태 관리.
+ * @public
+ */
+export declare function useToastLifecycle({ message, position, duration, onClose }: UseToastLifecycleOptions): UseToastLifecycleResult;