@ihabdevteam/core 0.37.0 → 0.39.0

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

@@ -0,0 +1,145 @@
+import type { ReactNode, KeyboardEvent } from 'react';
+import type { DeviceEntry, DeviceSide } from './HearingDeviceInfo';
+import './Panel.css';
+/**
+ * 패널 **한 줄** — `Panel` 이 담는 그릇이라면 이쪽은 그 안에 서는 줄이다.
+ *
+ * `Panel.tsx` 에서 갈라 나왔다. 한 파일에 컴포넌트 넷(Panel · PanelGrid · PanelRow ·
+ * PanelRowDevice)과 타입 열다섯이 함께 있었는데, 그릇을 고치러 들어온 사람이 줄의
+ * 12갈래 판별 합집합을 지나야 했다. 이 저장소가 이미 쓰는 방식이다
+ * (`trainingStepAudioPlayerTypes.ts` · `audioPlaybackRules.ts`).
+ *
+ * `Panel.tsx` 가 이것들을 다시 내보내므로 `@ihabdevteam/core/components/Panel` 에서
+ * 가져가던 곳은 그대로 돌아간다.
+ */
+type Base = {
+    label?: string;
+    sub?: string;
+    onClick?: () => void;
+    required?: boolean;
+    error?: string;
+    align?: 'horizontal' | 'vertical';
+    useFullWidth?: boolean;
+    icon?: ReactNode;
+};
+export type PanelRowToggle = Base & {
+    variant: 'toggle';
+    checked: boolean;
+    onChange: (v: boolean) => void;
+};
+export type PanelRowSegmented = Base & {
+    variant: 'segmented';
+    options: {
+        key: string;
+        label: string;
+    }[];
+    value: string;
+    onChange: (v: string) => void;
+    size?: 32 | 40 | 48;
+};
+export type DropdownItem = {
+    options: {
+        value: string;
+        label: string;
+    }[];
+    value: string;
+    onChange: (v: string) => void;
+    placeholder?: string;
+    /**
+     * 이 드롭다운 하나의 이름. 미지정 시 "행 라벨 + placeholder" 로 조합한다
+     * (생년월일 + 년 → "생년월일 년").
+     */
+    ariaLabel?: string;
+};
+export type PanelRowDropdown = Base & {
+    variant: 'dropdown';
+    options?: {
+        value: string;
+        label: string;
+    }[];
+    value?: string;
+    onChange?: (v: string) => void;
+    dropdowns?: DropdownItem[];
+};
+export type ButtonItem = {
+    label: ReactNode;
+    btnVariant?: string;
+    btnSize?: number;
+    disabled?: boolean;
+    onClick: () => void;
+};
+export type PanelRowButton = Base & {
+    variant: 'button';
+    buttonLabel?: ReactNode;
+    btnVariant?: string;
+    btnSize?: number;
+    disabled?: boolean;
+    onClick?: () => void;
+    buttons?: ButtonItem[];
+};
+export type PanelRowText = Base & {
+    variant: 'text';
+    value: string;
+    valueColor?: string;
+};
+export type PanelRowInput = Base & {
+    variant: 'input';
+    value: string;
+    onChange?: (v: string) => void;
+    onKeyDown?: (e: KeyboardEvent<HTMLInputElement | HTMLTextAreaElement>) => void;
+    /** Enter로 확정(제출 등). TextField가 IME 조합 중 Enter는 걸러 주므로 한글 입력에서도 안전하다. */
+    onEnter?: () => void;
+    placeholder?: string;
+    inputMode?: 'none' | 'text' | 'decimal' | 'numeric' | 'tel' | 'search' | 'email' | 'url';
+    readOnly?: boolean;
+    disabled?: boolean;
+    type?: 'text' | 'email' | 'password' | 'number' | 'tel' | 'url';
+    autoComplete?: string;
+    helperText?: string;
+    /** 최대 글자 수 — 설정 시 입력 제한 + 박스 안쪽 글자수 카운터 표시 */
+    maxLength?: number;
+    /** 글자수 카운터 표시 여부 (maxLength 설정 시, 기본 true) */
+    showCount?: boolean;
+    /** 여러 줄 입력(textarea) 모드 */
+    multiline?: boolean;
+    /** multiline 모드 기본 행 수 */
+    rows?: number;
+};
+export type PanelRowCustom = Base & {
+    variant: 'custom';
+    children: ReactNode;
+};
+/** 라벨/우측 분리 없이 설명 문단을 통으로 표시하는 행 */
+export type PanelRowDescription = {
+    variant: 'description';
+    children: ReactNode;
+};
+/** 빈 상태 표현 — Panel의 `empty` prop이 내부적으로 이 variant로 렌더한다. 단독으로도 사용 가능. */
+export type PanelRowEmpty = {
+    variant: 'empty';
+    children: ReactNode;
+};
+/** 로딩 스피너 1개만 중앙에 표시 — Panel의 `loading` prop이 내부적으로 이 variant로 렌더한다. */
+export type PanelRowLoading = {
+    variant: 'loading';
+};
+export type PanelRowChildren = {
+    label?: ReactNode;
+    sub?: string;
+    onClick?: () => void;
+    children?: ReactNode;
+    align?: 'horizontal' | 'vertical';
+    icon?: ReactNode;
+};
+export type PanelRowProps = PanelRowToggle | PanelRowSegmented | PanelRowDropdown | PanelRowButton | PanelRowText | PanelRowInput | PanelRowCustom | PanelRowDescription | PanelRowEmpty | PanelRowLoading | PanelRowChildren;
+export declare function PanelRow(props: PanelRowProps): import("react").JSX.Element;
+export type { DeviceSide };
+export interface PanelRowDeviceProps {
+    devices: {
+        좌: DeviceEntry | null;
+        우: DeviceEntry | null;
+    };
+    /** 있으면 각 쪽 이름 옆에 '착용 해제'가 선다 — 그 쪽의 '지금 착용중' 만 내린다(이력은 남는다) */
+    onRelease?: (side: DeviceSide) => void;
+}
+export declare function PanelRowDevice({ devices, onRelease }: PanelRowDeviceProps): import("react").JSX.Element;

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/Popup/ConfirmPopup.d.ts

@@ -28,11 +28,25 @@ export interface ConfirmPopupProps {
     confirmDisabled?: boolean;
     /** true면 취소 버튼을 숨긴다(단순 안내·닫기 전용). 기본 false */
     hideCancel?: boolean;
-    /** 확인/취소 왼쪽에 놓는 부가 액션(삭제 등). 클릭 후 팝업이 닫힌다. */
+    /**
+     * 확인/취소 왼쪽에 놓는 부가 액션(삭제·연결 해제 등).
+     *
+     * 계약은 `onConfirm` 과 같다 — `close` 를 받고 `closeOnClick` 으로 닫힘을 고른다.
+     * **실패할 수 있는 비동기 동작**이 여기 오기 때문이다. 곁 단추는 파괴적인 일을
+     * 맡는 자리인데(주 단추는 '그대로 두기' 여야 한다), 예전에는 누르면 무조건 닫혀
+     * 실패해도 까닭을 그 자리에 못 보였다 — 사람은 눌렀는데 아무 말 없이 창이 사라진
+     * 것만 본다. 성공했을 때만 닫으려면 `closeOnClick: false` 로 두고 `close()` 를
+     * 직접 부른다.
+     */
     extraAction?: {
         label: ReactNode;
         variant?: ButtonVariant;
-        onClick: () => void;
+        /** `close` 를 받는다 — 성공했을 때만 닫는 식으로 쓴다(async 지원). */
+        onClick: (close: () => void) => void | Promise<void>;
+        /** false면 자동으로 닫지 않음 — onClick이 받은 close로 닫힘 시점을 제어. 기본 true */
+        closeOnClick?: boolean;
+        /** 곁 단추만 따로 비활성 (처리 중 등). 팝업 전체의 busy 와는 별개로 얹힌다. */
+        disabled?: boolean;
     };
     /**
      * 확인 클릭 시 실행. `close`로 직접 닫을 수 있음(async 지원).

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

@@ -26,8 +26,25 @@ export default function ConfirmPopup(props) {
             ...(extraAction ? [{
                     label: extraAction.label,
                     variant: extraAction.variant ?? 'default',
-                    disabled: busy,
-                    onClick: ({ closeWithAnimation }) => { extraAction.onClick(); closeWithAnimation(); },
+                    disabled: extraAction.disabled || busy,
+                    // 확인 단추와 같은 재진입 방지를 받는다. 여기 오는 것은 파괴적이고 되돌릴 수
+                    // 없는 일(삭제·연결 해제)이라, 두 번 눌려 두 번 나가면 첫 번째만 뜻이 있고
+                    // 두 번째는 엉뚱한 실패로 돌아온다.
+                    onClick: async ({ closeWithAnimation }) => {
+                        if (busyRef.current)
+                            return;
+                        busyRef.current = true;
+                        setBusy(true);
+                        try {
+                            await extraAction.onClick(closeWithAnimation);
+                            if (extraAction.closeOnClick ?? true)
+                                closeWithAnimation();
+                        }
+                        finally {
+                            busyRef.current = false;
+                            setBusy(false);
+                        }
+                    },
                 }] : []),
             ...(hideCancel ? [] : [{
                     label: cancelLabel ?? t('common.cancel', '취소'),

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/Word/wordTablePrint.js

@@ -79,6 +79,12 @@ export function captureHtml(els, paperW, paperH, autoPrint = false, fileName = '
             .forEach(s => s.remove());
         return `<div class="paper-wrap">${headHtml}${clone.outerHTML}</div>`;
     }).join('\n');
+    /* 이 꾸러미의 CSS 는 전부 `.ihabdevteam-core-scope` **아래**에 산다(styles.css 스코핑).
+       위에서 `document.styleSheets` 를 통째로 베껴 넣어도, 새 문서의 body 에 이 클래스가
+       없으면 2천 개 넘는 규칙이 하나도 안 걸린다 — 글자는 브라우저 기본 크기로, 굵기는
+       normal 로 떨어진다. 화면은 앱 셸의 `<body class="ihabdevteam-core-scope">` 가
+       받쳐 주지만 이 문서는 손으로 짓는 것이라 그 밖에 있다. `data-theme` 을 html 에
+       얹는 것과 같은 결의 처리다. */
     /* eslint-disable no-useless-escape -- 아래 문자열의 `<\/script>`는 실제 <script> 태그로 파싱되어 삽입되므로, 이스케이프가 없으면 바깥 <script> 태그가 조기 종료된다 */
     return `<!DOCTYPE html>
 <html data-theme="${theme}">
@@ -133,7 +139,7 @@ export function captureHtml(els, paperW, paperH, autoPrint = false, fileName = '
       }
     </style>
   </head>
-  <body>
+  <body class="ihabdevteam-core-scope">
     ${wraps}
     <button class="button button48 button48--dot button--variant-default button--align-center new-window-close" onclick="window.close()"><span class="button__icon button__icon--medium"><svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="button__icon-svg"><path d="M18 6 6 18"/><path d="m6 6 12 12"/></svg></span></button>
   <script>

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