@ihabdevteam/core 0.38.0 → 0.39.0

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

@@ -0,0 +1,144 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from '../utils/cx';
+import { useId } from 'react';
+import { useTranslation } from 'react-i18next';
+import Toggle from './Toggle';
+import SegmentedControl from './SegmentedControl';
+import Dropdown from './Dropdown';
+import Button from './Button';
+import Badge from './Badge';
+import { deviceKindVariant } from '../utils/deviceKind';
+import TextField from './TextField';
+import Loader from './Loader';
+import './Panel.css';
+const noop = () => { };
+export function PanelRow(props) {
+    // toggle 행의 라벨-스위치 연결용 id — 모든 variant에서 훅 호출 순서를 유지하기 위해
+    // 조건부 return들보다 앞에서 무조건 호출한다 (사용하지 않는 variant에서는 그냥 버려짐)
+    const uid = useId();
+    // children 기반 하위 호환 모드
+    if (!('variant' in props)) {
+        const { label, sub, onClick, children, align = 'horizontal', icon } = props;
+        const handleKeyDown = (e) => {
+            if (!onClick)
+                return;
+            // 우측 children 안의 버튼/토글 등이 자체적으로 Enter/Space를 처리하므로,
+            // 행 자기 자신에서 발생한 키 입력만 행 클릭으로 취급한다
+            if (e.target !== e.currentTarget)
+                return;
+            if (e.key === 'Enter' || e.key === ' ') {
+                e.preventDefault();
+                onClick();
+            }
+        };
+        return (_jsxs("div", { className: cx('panel-row', align === 'vertical' ? 'panel-row--vertical' : '', onClick ? 'panel-row--clickable' : ''), onClick: onClick, onKeyDown: onClick ? handleKeyDown : undefined, role: onClick ? 'button' : undefined, tabIndex: onClick ? 0 : undefined, children: [icon != null && _jsx("div", { className: "panel-row__icon", children: icon }), label != null && (_jsxs("div", { className: "panel-row__left", children: [_jsx("div", { className: "panel-row__label body-3", children: label }), sub && _jsx("div", { className: "panel-row__sub caption-1", children: sub })] })), _jsx("div", { className: "panel-row__right", children: children })] }));
+    }
+    // 설명 전용 행 — 라벨/우측 구조 없이 문단만 렌더
+    if (props.variant === 'description') {
+        const p = props;
+        return (_jsx("div", { className: "panel-row panel-row--block", children: _jsx("p", { className: "panel-row__description body-3", children: p.children }) }));
+    }
+    // 빈 상태 — 라벨 없이 중앙 정렬된 한 줄
+    if (props.variant === 'empty') {
+        const p = props;
+        return _jsx("div", { className: "panel-row panel-row--empty body-3", children: p.children });
+    }
+    // 로딩 — 중앙 스피너 1개
+    if (props.variant === 'loading') {
+        return _jsx("div", { className: "panel-row panel-row--loading", children: _jsx(Loader, { size: 28 }) });
+    }
+    // custom 행에 label이 없으면 좌/우 분할 없이 children을 그대로 꽉 채워 렌더
+    // (CodeBox처럼 라벨과 짝지을 수 없는 큰 블록 콘텐츠를 행 구조 안에 넣을 때 사용)
+    if (props.variant === 'custom' && !props.label) {
+        const p = props;
+        return (_jsx("div", { className: "panel-row panel-row--block", children: p.children }));
+    }
+    const { variant, label, sub, onClick, required, error, align = 'horizontal', useFullWidth = false, icon } = props;
+    let right = null;
+    // toggle 행만 왼쪽 라벨(panel-row__label)을 <label htmlFor>로 렌더해 스위치와 프로그래밍적으로
+    // 연결한다 — 그 전엔 시각적으로만 옆에 붙어있어 라벨 텍스트를 클릭해도 토글이 안 되고
+    // 스크린리더도 이 스위치가 뭘 위한 건지 안내하지 못했다.
+    const toggleId = variant === 'toggle' ? `panel-toggle-${uid}` : undefined;
+    if (variant === 'toggle') {
+        const p = props;
+        right = _jsx(Toggle, { checked: p.checked, onChange: p.onChange, id: toggleId });
+    }
+    else if (variant === 'segmented') {
+        const p = props;
+        // dropdown 행과 동일하게, PanelRow 왼쪽 라벨은 <label htmlFor>가 아닌 일반 div라서
+        // SegmentedControl에 ariaLabel로 넘겨야 스크린리더가 이름 없는 라디오그룹으로 안내하지 않는다.
+        right = _jsx(SegmentedControl, { options: p.options, value: p.value, onChange: p.onChange, size: p.size ?? 40, ariaLabel: label });
+    }
+    else if (variant === 'dropdown') {
+        const p = props;
+        const dropdowns = p.dropdowns?.length ? (_jsx("div", { className: `panel-row__dropdown-group${useFullWidth ? ' panel-row__dropdown-group--full' : ''}`, children: p.dropdowns.map((d, i) => (_jsx("div", { className: useFullWidth ? 'panel-row__dropdown-item--full' : undefined, children: _jsx(Dropdown, { options: d.options, value: d.value, onChange: d.onChange, placeholder: d.placeholder, block: useFullWidth, error: !!error, 
+                    // 한 행에 여러 개가 놓이므로 행 라벨만 넘기면 셋 다 "생년월일" 이라는 같은 이름이 된다.
+                    // aria-label 이 있으면 스크린리더는 트리거의 화면 텍스트(년/월/일)를 읽지 않으므로
+                    // 사용자는 어느 것이 무엇인지 구별할 수 없다 — placeholder 를 붙여 구별되게 한다.
+                    ariaLabel: d.ariaLabel ?? ([label, d.placeholder].filter(Boolean).join(' ') || undefined) }) }, i))) })) : (
+        // PanelRow 왼쪽 라벨(panel-row__label)은 <label htmlFor>가 아니라 그냥 div라서 트리거 버튼과
+        // 프로그래밍적으로 연결되지 않는다 — ariaLabel로 직접 이름을 넘긴다 (TextField의 ariaLabel과 동일 패턴)
+        _jsx(Dropdown, { options: p.options ?? [], value: p.value ?? '', onChange: p.onChange ?? noop, block: useFullWidth, error: !!error, ariaLabel: label }));
+        right = error ? (_jsxs("div", { className: `panel-row__dropdown-error-wrap${useFullWidth ? ' panel-row__dropdown-error-wrap--full' : ''}`, children: [dropdowns, _jsx("span", { className: "caption-1 panel-row__error", role: "alert", children: error })] })) : dropdowns;
+    }
+    else if (variant === 'button') {
+        const p = props;
+        if (p.buttons?.length) {
+            right = (_jsx("div", { className: "panel-row__button-group", children: p.buttons.map((btn, i) => (_jsx(Button, { size: btn.btnSize ?? 40, variant: btn.btnVariant ?? 'default', disabled: btn.disabled, onClick: btn.onClick, children: btn.label }, i))) }));
+        }
+        else {
+            right = (_jsx(Button, { size: p.btnSize ?? 40, variant: p.btnVariant ?? 'default', disabled: p.disabled, onClick: p.onClick, children: p.buttonLabel }));
+        }
+    }
+    else if (variant === 'text') {
+        const p = props;
+        right = _jsx("span", { className: `panel-row__text body-2${useFullWidth ? ' panel-row__text--full' : ''}`, style: p.valueColor ? { color: p.valueColor } : undefined, children: p.value });
+    }
+    else if (variant === 'input') {
+        const p = props;
+        right = (_jsxs("div", { className: `panel-row__input-wrap${useFullWidth ? ' panel-row__input-wrap--full' : ''}`, children: [_jsx(TextField, { value: p.value, onChange: p.onChange ?? noop, onKeyDown: p.onKeyDown, onEnter: p.onEnter, placeholder: p.placeholder, inputMode: p.inputMode, readOnly: p.readOnly, disabled: p.disabled, type: p.type, autoComplete: p.autoComplete, maxLength: p.maxLength, showCount: p.showCount, multiline: p.multiline, rows: p.rows, fullWidth: useFullWidth, error: error, ariaLabel: label, required: required }), p.helperText && _jsx("div", { className: "panel-row__helper caption-1", children: p.helperText })] }));
+    }
+    else if (variant === 'custom') {
+        const p = props;
+        right = p.children;
+    }
+    const isLabelFixed = variant === 'input' || variant === 'dropdown' || ((variant === 'text' || variant === 'custom') && useFullWidth);
+    // 위 children 모드와 동일한 키보드 처리 — 이쪽 경로에만 빠져 있어서,
+    // variant 모드에 onClick을 주면 조용히 마우스 전용이 된다(현재 사용처는 없지만 예방).
+    const handleKeyDown = (e) => {
+        if (!onClick)
+            return;
+        if (e.target !== e.currentTarget)
+            return;
+        if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault();
+            onClick();
+        }
+    };
+    return (_jsxs("div", { className: cx('panel-row', align === 'vertical' ? 'panel-row--vertical' : '', isLabelFixed ? 'panel-row--label-fixed' : '', variant === 'text' ? 'panel-row--text' : '', onClick ? 'panel-row--clickable' : ''), onClick: onClick, onKeyDown: onClick ? handleKeyDown : undefined, role: onClick ? 'button' : undefined, tabIndex: onClick ? 0 : undefined, children: [icon != null && _jsx("div", { className: "panel-row__icon", children: icon }), _jsxs("div", { className: "panel-row__left", children: [toggleId ? (_jsxs("label", { htmlFor: toggleId, className: "panel-row__label body-3", children: [label, required && _jsx("span", { className: "required-mark", children: "*" })] })) : (_jsxs("div", { className: "panel-row__label body-3", children: [label, required && _jsx("span", { className: "required-mark", children: "*" })] })), sub && _jsx("div", { className: "panel-row__sub caption-1", children: sub })] }), _jsx("div", { className: "panel-row__right", children: right })] }));
+}
+/**
+ * 제목 아래 한 줄로 세울 곁정보 — 브랜드·착용형태.
+ *
+ * 제목으로 이미 쓴 값과 빈 값, 그리고 서로 같은 값을 걷어 낸다. 걷어 내지 않으면
+ * 브랜드도 형태도 '기타' 인 기기가 **'기타 · 기타'** 로 떴다(같은 말이 두 번).
+ */
+function 메타(d) {
+    const 제목 = d.productName || d.brand;
+    const 조각 = [d.brand, d.fitType].filter((v) => !!v && v !== 제목);
+    return [...new Set(조각)].join(' · ');
+}
+export function PanelRowDevice({ devices, onRelease }) {
+    const { t } = useTranslation();
+    const SIDES = ['좌', '우'];
+    return (_jsx("div", { className: "panel-row panel-row--device", children: SIDES.map(side => {
+            const d = devices[side];
+            const sideLabel = side === '좌' ? t('device.direction.left', '좌') : t('device.direction.right', '우');
+            return (_jsxs("div", { className: "panel-row__device-column", children: [_jsxs("div", { className: "panel-row__device-head", children: [_jsx("span", { className: "panel-row__device-side body-2b", children: sideLabel }), d && onRelease && (
+                            /* 표의 줄 끝 단추와 같은 모양·같은 말 — 하는 일도 같다.
+                               이력에서 지우는 것이 아니라 '지금 끼고 있음' 만 내린다
+                               (잠시 안 씀·수리 보냄 같은 경우가 실제로 있다). */
+                            _jsx(Button, { size: 32, type: "dot", icon: "x", ariaLabel: t('customers.device.unwear', '착용 해제'), showTooltipInfo: t('customers.device.unwear', '착용 해제'), onClick: () => onRelease(side) }))] }), d ? (_jsxs("div", { className: "panel-row__device-info", children: [_jsxs("span", { className: "panel-row__device-kind", children: [d.device && _jsx(Badge, { size: "small", variant: deviceKindVariant(d.device), fill: "soft", label: d.device }), 메타(d) && _jsx("span", { className: "panel-row__device-detail body-3", children: 메타(d) })] }), _jsx("span", { className: "panel-row__device-name body-2b", children: d.productName || d.brand }), _jsx("span", { className: "panel-row__device-date caption-1", children: t('customers.device.wornSince', { date: `${d.wornYear}.${d.wornMonth}.${d.wornDay}` }) })] })) : (_jsx("span", { className: "panel-row__device-empty body-3", children: t('customers.device.notRegistered', '미등록') }))] }, side));
+        }) }));
+}

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

@@ -1,66 +1,13 @@
 'use client';
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import { getErrorMessage } from '../../utils/errorMessage';
+import { computePeaksFromUrl } from '../../utils/audioPeaks';
 import './TrainingStepAudioPlayer.css';
 /**
  * waveform 바 최소 픽셀 — 렌더 높이가 이 값 이하이면 바를 그리지 않는다(문장·소음 공통).
  * 그려지는 바는 항상 이 값을 넘는 높이만 표시하며(가로 폭은 BAR_WIDTH=3px), 그 이하는 숨긴다.
  */
 const MIN_BAR_PX = 4;
-// windowSeconds: 지정 시 파일의 처음 N초만 사용(소음을 문장 재생시간만큼만 그릴 때).
-// 컴포넌트 상태를 참조하지 않는 순수 계산이라 모듈 스코프로 분리 — 매 렌더 재생성되지 않는다.
-async function decodeAndComputePeaks(arrayBuffer, bars, windowSeconds) {
-    try {
-        const AudioCtxConstructor = window.AudioContext || window.webkitAudioContext;
-        const audioCtx = new AudioCtxConstructor();
-        const decoded = await audioCtx.decodeAudioData(arrayBuffer.slice(0));
-        const channelData = decoded.numberOfChannels > 0 ? decoded.getChannelData(0) : null;
-        if (!channelData)
-            return null;
-        const total = (windowSeconds && windowSeconds > 0)
-            ? Math.min(channelData.length, Math.floor(windowSeconds * decoded.sampleRate))
-            : channelData.length;
-        const usableLen = Math.max(bars, total);
-        const blockSize = Math.floor(usableLen / bars) || 1;
-        const peaks = new Array(bars).fill(0).map((_, i) => {
-            const start = i * blockSize;
-            const end = Math.min(start + blockSize, usableLen);
-            let max = 0;
-            for (let j = start; j < end; j++) {
-                const v = Math.abs(channelData[j]);
-                if (v > max)
-                    max = v;
-            }
-            return max;
-        });
-        try {
-            audioCtx.close && audioCtx.close();
-        }
-        catch (e) { }
-        // 절대 진폭(0~1, full-scale 기준) 반환 — 문장/소음이 같은 기준을 쓰게 해 dBFS 미터와 일치.
-        return peaks;
-    }
-    catch (e) {
-        return null;
-    }
-}
-async function computePeaksFromUrl(url, bars, windowSeconds) {
-    try {
-        const resp = await fetch(url);
-        const arrayBuffer = await resp.arrayBuffer();
-        return await decodeAndComputePeaks(arrayBuffer, bars, windowSeconds);
-    }
-    catch (e) {
-        try {
-            const errMsg = getErrorMessage(e);
-            if (import.meta.env?.DEV)
-                console.log('WaveForm: computePeaksFromUrl failed', { url, err: errMsg });
-        }
-        catch (ee) { }
-        return null;
-    }
-}
 export default function WaveForm(props) {
     const { src, segments, progress = 0, waveProgressRef, noiseSrc, noiseLevel = 0, noiseSpeed = 1, totalDuration = 0, mainVolume = 1, onReadyChange, showSoundWaveForm = true } = props;
     const waveformRef = useRef(null);

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

@@ -1,18 +1,5 @@
-/** @public */
-export type CoreNoiseType = 'defaultNoise' | 'street' | 'restaurant' | 'buzz';
-/** @public */
-export type CoreNoiseSettings = {
-    enabled: boolean;
-    type: CoreNoiseType;
-    /** 0–9. 0이면 소음 비활성화. (소음 음원을 +7dB 증폭한 뒤 상한을 4→9로 확장 — 실제 volume = level/9) */
-    level: number;
-    /** 소음 재생 속도(playbackRate). 0.75–1.25, 기본 1. */
-    speed: number;
-    /** 문장(메인) 재생 소리(볼륨). 0–1, 기본 1. 계정 설정("훈련" 패널)과 훈련 화면 툴팁이 함께 영속화한다. */
-    mainVolume: number;
-    /** 문장(메인) 재생 속도(playbackRate). 0.5–1.5, 기본 1. 계정 설정("훈련" 패널)과 훈련 화면 툴팁이 함께 영속화한다. */
-    mainSpeed: number;
-};
+import type { CoreNoiseSettings } from '../../types/training';
+export type { CoreNoiseType, CoreNoiseSettings } from '../../types/training';
 /** @public */
 export declare const LEVEL_MAX = 9;
 /** @public */

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

@@ -1,28 +1,10 @@
-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
+ * 옛 자리 — 실제 몸은 `hooks/useAnchoredMenu.ts` 에 있다.
+ *
+ * 네 컴포넌트(Dropdown · DatePicker · Header · BottomNav)가 함께 쓰는 훅이라
+ * 한 컴포넌트 곁이 아니라 `hooks/` 가 제자리다. 다만
+ * `@ihabdevteam/core/components/useAnchoredMenu` 로 가져가는 곳이 있을 수 있어
+ * 이 자리를 남겨 둔다.
  */
-export declare function useAnchoredMenu<Trigger extends HTMLElement = HTMLElement, Menu extends HTMLElement = HTMLElement>({ computeStyle, onScroll, onResize, ignoreOutsideClickSelector, }: UseAnchoredMenuOptions): UseAnchoredMenuResult<Trigger, Menu>;
+export { useAnchoredMenu } from '../hooks/useAnchoredMenu';
+export type { UseAnchoredMenuOptions, UseAnchoredMenuResult } from '../hooks/useAnchoredMenu';

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

@@ -1,72 +1,9 @@
-'use client';
-import { useCallback, useEffect, useRef, useState } from 'react';
 /**
- * 트리거 요소에 fixed 포지션으로 앵커링되는 메뉴/드롭다운/팝오버의 공용 로직.
- * 열림상태 + 위치 계산 + 바깥클릭/스크롤/리사이즈 처리를 담당하고, 렌더링(포탈 등)은
- * 사용하는 쪽에서 담당한다. Dropdown, DatePicker, BottomNav의 "더보기" 메뉴가 이 훅을 쓴다.
- * @public
+ * 옛 자리 — 실제 몸은 `hooks/useAnchoredMenu.ts` 에 있다.
+ *
+ * 네 컴포넌트(Dropdown · DatePicker · Header · BottomNav)가 함께 쓰는 훅이라
+ * 한 컴포넌트 곁이 아니라 `hooks/` 가 제자리다. 다만
+ * `@ihabdevteam/core/components/useAnchoredMenu` 로 가져가는 곳이 있을 수 있어
+ * 이 자리를 남겨 둔다.
  */
-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 };
-}
+export { useAnchoredMenu } from '../hooks/useAnchoredMenu';

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

@@ -1,54 +1,11 @@
-import type { SpeakerPos } from '../types/audio';
 /**
- * @public
- * SoundCompass 오케스트레이션 참조 훅.
+ * 옛 자리 — 실제 몸은 `hooks/useSoundCompassExam.ts` 에 있다.
  *
- * SoundCompass 자체는 제어형(표현) 컴포넌트라 순서·타이밍·점수·진행을 갖지 않는다.
- * 이 훅이 그 "부모(검사 컨트롤러)" 역할의 기본 구현을 제공한다 —
- * 큐 셔플, 문제 재생 타이밍, 선택 수집, 피드백, 진행/점수, 완료 콜백.
- *
- * 반환한 `bind`를 `<SoundCompass {...exam.bind} />`처럼 펼쳐 넣으면 된다.
- * 다른 동작이 필요하면 이 훅을 복사·수정하거나, SoundCompass의 제어 props를
- * 직접 구동해도 된다.
+ * 이것은 **머리 없는 오케스트레이터**다. `SoundCompass` 는 시키는 대로 그리기만 하고
+ * 순서·타이밍·점수·진행은 이 훅이 진다(SoundCompass.md 에 그렇게 적혀 있다).
+ * 코어의 어느 컴포넌트도 이것을 쓰지 않는다 — 소비자가 쓴다. 그러니 컴포넌트 곁이
+ * 아니라 `hooks/` 가 제자리다. 소리방향성이
+ * `@ihabdevteam/core/components/useSoundCompassExam` 로 가져가고 있어 이 자리를 남긴다.
  */
-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;
+export { useSoundCompassExam } from '../hooks/useSoundCompassExam';
+export type { SoundCompassMode, SoundCompassPhase, SoundCompassExam, UseSoundCompassExamOptions } from '../hooks/useSoundCompassExam';

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>;