@ihabdevteam/core 0.8.0

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

@@ -0,0 +1,45 @@
+'use client';
+import { useEffect, useState, useContext, createContext } from 'react';
+/** @public */
+export const MediaQueryOverrideContext = createContext(null);
+// '(max-width: 767px)' / '(max-width: 768px)' 같은 모바일 판정 쿼리인지 추정
+function isMobileQuery(query) {
+    return /max-width:\s*7[0-9][0-9]px/.test(query);
+}
+/** @public */
+export default function useMediaQuery(query) {
+    const override = useContext(MediaQueryOverrideContext);
+    const getMatches = (q) => {
+        if (typeof window === 'undefined' || !window.matchMedia)
+            return false;
+        return window.matchMedia(q).matches;
+    };
+    const [matches, setMatches] = useState(getMatches(query));
+    // query가 바뀌면 새 matchMedia 결과로 즉시 동기화(구독 시작 전 값이 stale할 수 있음) —
+    // window.matchMedia(외부 시스템) 구독의 표준 패턴이다
+    /* eslint-disable react-hooks/set-state-in-effect */
+    useEffect(() => {
+        if (typeof window === 'undefined' || !window.matchMedia)
+            return;
+        const mq = window.matchMedia(query);
+        const onChange = (e) => setMatches(e.matches);
+        const mql = mq;
+        if (mql.addEventListener)
+            mql.addEventListener('change', onChange);
+        else if (mql.addListener)
+            mql.addListener(onChange);
+        setMatches(mq.matches);
+        return () => {
+            if (mql.removeEventListener)
+                mql.removeEventListener('change', onChange);
+            else if (mql.removeListener)
+                mql.removeListener(onChange);
+        };
+    }, [query]);
+    /* eslint-enable react-hooks/set-state-in-effect */
+    // 오버라이드가 있고 모바일 판정 쿼리이면 강제값 사용
+    if (override && typeof override.mobile === 'boolean' && isMobileQuery(query)) {
+        return override.mobile;
+    }
+    return matches;
+}

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

@@ -0,0 +1,23 @@
+/**
+ * 클라이언트 페이지네이션 — 목록·페이지크기·현재 페이지로 현재 쪽 항목·총 쪽수·보정된
+ * 현재 쪽을 낸다. 목록이 줄어 page 가 총 쪽수를 넘으면 마지막 쪽으로 조인다(curPage).
+ * 한 컴포넌트에서 여러 목록(세트·카드 등)을 각각 페이징하려면 여러 번 불러도 된다.
+ *
+ * **양쪽 다 조인다.** 예전엔 상한만 조여서 1보다 작은 page 가 들어오면 slice 의 음수
+ * 인덱스가 그대로 먹혔다 — 실측: page=0 이면 빈 목록, page=-1 이면 3~7번째 항목이 1쪽인
+ * 것처럼 나왔다. perPage 도 1 미만이거나 숫자가 아니면 총 쪽수가 Infinity/NaN 이 되어
+ * 목록이 통째로 사라졌다. 지금 쓰는 Pagination 은 Math.max(1, …)와 disabled 로 막고
+ * 있어 그런 값이 오지 않지만, 이 훅은 page·perPage 를 밖에서 받으므로 계약 쪽에서 닫는다.
+ *
+ * **한 벌만 둔다.** 전에는 회원 앱과 어드민에 사본이 하나씩 있었고, 갈라지지 않게
+ * 본문을 글자 단위로 견주는 시험(usePagedList.sync.test.ts)까지 두고 있었다. 사본을
+ * 둔 이유로 적힌 것은 "어드민이 앱 소스(src/)를 보는 별칭이 없다" 였는데, 어드민은
+ * core 는 가져다 쓴다(@ihabdevteam/core/hooks). 그래서 여기로 옮겼다 — 두 앱 모두
+ * 이 한 벌을 가리키므로 갈라질 수가 없다.
+ * @public
+ */
+export declare function usePagedList<T>(items: T[], perPage: number, page: number): {
+    pageItems: T[];
+    totalPages: number;
+    curPage: number;
+};

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

@@ -0,0 +1,26 @@
+import { useMemo } from 'react';
+/**
+ * 클라이언트 페이지네이션 — 목록·페이지크기·현재 페이지로 현재 쪽 항목·총 쪽수·보정된
+ * 현재 쪽을 낸다. 목록이 줄어 page 가 총 쪽수를 넘으면 마지막 쪽으로 조인다(curPage).
+ * 한 컴포넌트에서 여러 목록(세트·카드 등)을 각각 페이징하려면 여러 번 불러도 된다.
+ *
+ * **양쪽 다 조인다.** 예전엔 상한만 조여서 1보다 작은 page 가 들어오면 slice 의 음수
+ * 인덱스가 그대로 먹혔다 — 실측: page=0 이면 빈 목록, page=-1 이면 3~7번째 항목이 1쪽인
+ * 것처럼 나왔다. perPage 도 1 미만이거나 숫자가 아니면 총 쪽수가 Infinity/NaN 이 되어
+ * 목록이 통째로 사라졌다. 지금 쓰는 Pagination 은 Math.max(1, …)와 disabled 로 막고
+ * 있어 그런 값이 오지 않지만, 이 훅은 page·perPage 를 밖에서 받으므로 계약 쪽에서 닫는다.
+ *
+ * **한 벌만 둔다.** 전에는 회원 앱과 어드민에 사본이 하나씩 있었고, 갈라지지 않게
+ * 본문을 글자 단위로 견주는 시험(usePagedList.sync.test.ts)까지 두고 있었다. 사본을
+ * 둔 이유로 적힌 것은 "어드민이 앱 소스(src/)를 보는 별칭이 없다" 였는데, 어드민은
+ * core 는 가져다 쓴다(@ihabdevteam/core/hooks). 그래서 여기로 옮겼다 — 두 앱 모두
+ * 이 한 벌을 가리키므로 갈라질 수가 없다.
+ * @public
+ */
+export function usePagedList(items, perPage, page) {
+    const size = Number.isFinite(perPage) && perPage >= 1 ? Math.floor(perPage) : 1;
+    const totalPages = Math.max(1, Math.ceil(items.length / size));
+    const curPage = Number.isFinite(page) ? Math.min(Math.max(1, Math.floor(page)), totalPages) : 1;
+    const pageItems = useMemo(() => items.slice((curPage - 1) * size, curPage * size), [items, curPage, size]);
+    return { pageItems, totalPages, curPage };
+}

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

@@ -0,0 +1,8 @@
+/**
+ * 장식 배경 컴포넌트(PromoBannerBg_* / PassCardBg_*)가 공통으로 쓰는 훅.
+ * 반환한 ref를 배경 루트 `<div>`에 달면, 마운트 시 그 부모 요소에 배경별 theme(CSS var 등)을
+ * 주입하고 언마운트 시 정리한다. 각 variant가 반복하던 useRef + useLayoutEffect 보일러플레이트를 모은다.
+ *
+ * theme/inject/clear는 모두 모듈 레벨 상수·함수라 실질적으로 마운트 시 1회만 실행된다.
+ */
+export declare function useParentBgTheme<Theme>(theme: Theme, inject: (parent: HTMLElement | null, theme: Theme) => void, clear: (parent: HTMLElement | null) => void): import("react").RefObject<HTMLDivElement | null>;

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

@@ -0,0 +1,18 @@
+'use client';
+import { useLayoutEffect, useRef } from 'react';
+/**
+ * 장식 배경 컴포넌트(PromoBannerBg_* / PassCardBg_*)가 공통으로 쓰는 훅.
+ * 반환한 ref를 배경 루트 `<div>`에 달면, 마운트 시 그 부모 요소에 배경별 theme(CSS var 등)을
+ * 주입하고 언마운트 시 정리한다. 각 variant가 반복하던 useRef + useLayoutEffect 보일러플레이트를 모은다.
+ *
+ * theme/inject/clear는 모두 모듈 레벨 상수·함수라 실질적으로 마운트 시 1회만 실행된다.
+ */
+export function useParentBgTheme(theme, inject, clear) {
+    const ref = useRef(null);
+    useLayoutEffect(() => {
+        const parent = ref.current?.parentElement ?? null;
+        inject(parent, theme);
+        return () => clear(parent);
+    }, [theme, inject, clear]);
+    return ref;
+}

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

@@ -0,0 +1,28 @@
+export interface PasswordChangeMsg {
+    type: 'error' | 'success';
+    text: string;
+}
+/**
+ * 비밀번호 변경 폼 상태와 핸들러를 캡슐화한 훅.
+ * showModal 상태는 컴포넌트가 직접 관리 (훅 밖에 두어야 모달 열기 트리거 제어 가능).
+ */
+/**
+ * @public
+ */
+export declare function usePasswordChange(onChangePassword?: (current: string, next: string) => Promise<string | null>): {
+    pw: {
+        current: string;
+        next: string;
+        confirm: string;
+    };
+    setPw: import("react").Dispatch<import("react").SetStateAction<{
+        current: string;
+        next: string;
+        confirm: string;
+    }>>;
+    pwMsg: PasswordChangeMsg | null;
+    setPwMsg: import("react").Dispatch<import("react").SetStateAction<PasswordChangeMsg | null>>;
+    pwLoading: boolean;
+    handleChangePw: () => Promise<void>;
+    reset: () => void;
+};

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

@@ -0,0 +1,54 @@
+'use client';
+import { useCallback, useEffect, useRef, useState } from 'react';
+/**
+ * 비밀번호 변경 폼 상태와 핸들러를 캡슐화한 훅.
+ * showModal 상태는 컴포넌트가 직접 관리 (훅 밖에 두어야 모달 열기 트리거 제어 가능).
+ */
+/**
+ * @public
+ */
+export function usePasswordChange(onChangePassword) {
+    const [pw, setPw] = useState({ current: '', next: '', confirm: '' });
+    const [pwMsg, setPwMsg] = useState(null);
+    const [pwLoading, setPwLoading] = useState(false);
+    const clearTimerRef = useRef(null);
+    useEffect(() => {
+        return () => {
+            if (clearTimerRef.current !== null)
+                clearTimeout(clearTimerRef.current);
+        };
+    }, []);
+    const reset = useCallback(() => {
+        setPw({ current: '', next: '', confirm: '' });
+        setPwMsg(null);
+    }, []);
+    const handleChangePw = useCallback(async () => {
+        if (!pw.current) {
+            setPwMsg({ type: 'error', text: '현재 비밀번호를 입력하세요.' });
+            return;
+        }
+        // 길이·복잡도 규칙은 onChangePassword(앱 측)가 관리자 보안 정책으로 검증한다 —
+        // 여기서 고정 규칙을 두면 정책과 불일치가 생기므로 빈 값만 거른다.
+        if (!pw.next) {
+            setPwMsg({ type: 'error', text: '새 비밀번호를 입력하세요.' });
+            return;
+        }
+        if (pw.next !== pw.confirm) {
+            setPwMsg({ type: 'error', text: '새 비밀번호가 일치하지 않습니다.' });
+            return;
+        }
+        setPwLoading(true);
+        const err = onChangePassword ? await onChangePassword(pw.current, pw.next) : null;
+        setPwLoading(false);
+        if (err) {
+            setPwMsg({ type: 'error', text: err });
+            return;
+        }
+        setPwMsg({ type: 'success', text: '비밀번호가 변경되었습니다.' });
+        setPw({ current: '', next: '', confirm: '' });
+        if (clearTimerRef.current !== null)
+            clearTimeout(clearTimerRef.current);
+        clearTimerRef.current = setTimeout(() => setPwMsg(null), 1500);
+    }, [pw, onChangePassword]);
+    return { pw, setPw, pwMsg, setPwMsg, pwLoading, handleChangePw, reset };
+}

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

@@ -0,0 +1,12 @@
+/**
+ * 날짜를 "오늘 / 어제 / N일 전"으로 읽어 준다.
+ *
+ * 숙제가 언제 왔는지는 목록에서도(내 숙제) 실행 팝업에서도 같은 말로 보여야 해서
+ * 한곳에 둔다 — 두 곳에 따로 두면 한쪽만 고쳐져 같은 숙제가 화면마다 다른 날짜로
+ * 읽히게 된다.
+ *
+ * 날짜 경계가 아니라 24시간 단위로 센다(어제 23시는 오늘 01시에 "0일 전"). 숙제는
+ * "며칠쯤 됐나"를 가늠하는 용도라 이 정도로 충분하고, 시간대 처리도 들어가지 않는다.
+ */
+export declare function useRelativeDay(): (iso?: string | null) => string;
+export default useRelativeDay;

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

@@ -0,0 +1,30 @@
+'use client';
+import { useCallback } from 'react';
+import { useTranslation } from 'react-i18next';
+/**
+ * 날짜를 "오늘 / 어제 / N일 전"으로 읽어 준다.
+ *
+ * 숙제가 언제 왔는지는 목록에서도(내 숙제) 실행 팝업에서도 같은 말로 보여야 해서
+ * 한곳에 둔다 — 두 곳에 따로 두면 한쪽만 고쳐져 같은 숙제가 화면마다 다른 날짜로
+ * 읽히게 된다.
+ *
+ * 날짜 경계가 아니라 24시간 단위로 센다(어제 23시는 오늘 01시에 "0일 전"). 숙제는
+ * "며칠쯤 됐나"를 가늠하는 용도라 이 정도로 충분하고, 시간대 처리도 들어가지 않는다.
+ */
+export function useRelativeDay() {
+    const { t } = useTranslation();
+    return useCallback((iso) => {
+        if (!iso)
+            return '';
+        const ms = new Date(iso).getTime();
+        if (Number.isNaN(ms))
+            return '';
+        const days = Math.floor((Date.now() - ms) / 86400000);
+        if (days <= 0)
+            return t('myHomework.relativeDay.today', '오늘');
+        if (days === 1)
+            return t('myHomework.relativeDay.yesterday', '어제');
+        return t('myHomework.relativeDay.daysAgo', { n: days });
+    }, [t]);
+}
+export default useRelativeDay;

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

@@ -0,0 +1,46 @@
+/**
+ * 표의 쪽넘김 — 개수 보기 · 쪽 · 이번 쪽 줄.
+ *
+ * 고객 상세의 표 넷(방문·기기·훈련 오답·훈련 기록)이 같은 열 몇 줄을 저마다 베껴
+ * 갖고 있었다. 베낀 것 중에 **틀리기 쉬운 자리가 둘** 있어서 한 곳으로 모은다.
+ *
+ *  1. **줄이 줄어들면 지금 쪽이 총 쪽수를 넘을 수 있다.** 3쪽을 보다가 검색으로 다섯
+ *     줄만 남으면 3쪽은 없는 쪽이다 — 그대로 두면 빈 표가 뜬다. 늘 총 쪽수 안으로
+ *     당겨 온다(`이쪽`).
+ *  2. **정렬은 쪽넘김보다 앞에 와야 한다.** 뒤에서 하면 지금 보이는 25개 안에서만 줄이
+ *     섞여, 2쪽의 더 이른 날짜가 1쪽으로 올라오지 않는다. 이 훅은 **이미 정렬된 줄**을
+ *     받는다 — 차례를 거꾸로 쓰기 어렵게 만든 것이다.
+ *
+ * @public
+ */
+export declare function useTablePaging<T>(rows: readonly T[], resetOn?: unknown): {
+    pageRows: T[];
+    /** Toolbar 의 pageSize 자리에 그대로 넣는다 */
+    pageSizeProps: {
+        options: {
+            label: string;
+            value: string;
+        }[];
+        value: string;
+        onChange: (v: string) => void;
+    };
+    /** Toolbar 의 pagination 자리에 그대로 넣는다 */
+    paginationProps: {
+        page: number;
+        total: number;
+        onChange: import("react").Dispatch<import("react").SetStateAction<number>>;
+    };
+    setPage: import("react").Dispatch<import("react").SetStateAction<number>>;
+};
+/** 머리행 정렬 상태 — 같은 칸을 다시 누르면 방향이 뒤집힌다 @public */
+export declare function useTableSort<K extends string>(): {
+    정렬: {
+        key: K;
+        asc: boolean;
+    } | null;
+    칸: (label: string, key: K) => {
+        label: string;
+        sortDir: "desc" | "asc" | null;
+        onClick: () => void;
+    };
+};

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

@@ -0,0 +1,63 @@
+'use client';
+import { useCallback, useMemo, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import { VAP_PAGE_SIZE_OPTIONS } from './useVisitAllPanel';
+/**
+ * 표의 쪽넘김 — 개수 보기 · 쪽 · 이번 쪽 줄.
+ *
+ * 고객 상세의 표 넷(방문·기기·훈련 오답·훈련 기록)이 같은 열 몇 줄을 저마다 베껴
+ * 갖고 있었다. 베낀 것 중에 **틀리기 쉬운 자리가 둘** 있어서 한 곳으로 모은다.
+ *
+ *  1. **줄이 줄어들면 지금 쪽이 총 쪽수를 넘을 수 있다.** 3쪽을 보다가 검색으로 다섯
+ *     줄만 남으면 3쪽은 없는 쪽이다 — 그대로 두면 빈 표가 뜬다. 늘 총 쪽수 안으로
+ *     당겨 온다(`이쪽`).
+ *  2. **정렬은 쪽넘김보다 앞에 와야 한다.** 뒤에서 하면 지금 보이는 25개 안에서만 줄이
+ *     섞여, 2쪽의 더 이른 날짜가 1쪽으로 올라오지 않는다. 이 훅은 **이미 정렬된 줄**을
+ *     받는다 — 차례를 거꾸로 쓰기 어렵게 만든 것이다.
+ *
+ * @public
+ */
+export function useTablePaging(rows, resetOn) {
+    const { t } = useTranslation();
+    const [pageSize, setPageSizeRaw] = useState('25');
+    const [page, setPage] = useState(1);
+    /* 늘어놓는 차례가 바뀌면 첫 쪽으로 — 3쪽을 보던 중에 정렬하면 무엇이 위로 왔는지
+       못 본다. 렌더 중에 되돌린다(저장소의 다른 곳들과 같은 꼴: 값이 바뀐 그 렌더에서
+       바로 맞춰야 한 박자 늦은 화면이 안 뜬다). */
+    const [본것, set본것] = useState(resetOn);
+    if (본것 !== resetOn) {
+        set본것(resetOn);
+        if (page !== 1)
+            setPage(1);
+    }
+    const pageSizeOptions = useMemo(() => VAP_PAGE_SIZE_OPTIONS.map(o => ({ ...o, label: t('visits.showN', { n: o.value }) })), [t]);
+    /* 개수를 바꾸면 첫 쪽으로 — 25개씩 보다가 100개씩으로 바꿨는데 3쪽에 남아 있으면
+       대부분의 경우 빈 표가 된다 */
+    const setPageSize = useCallback((v) => { setPageSizeRaw(v); setPage(1); }, []);
+    const total = Math.max(1, Math.ceil(rows.length / Number(pageSize)));
+    const 이쪽 = Math.min(page, total);
+    const pageRows = useMemo(() => rows.slice((이쪽 - 1) * Number(pageSize), 이쪽 * Number(pageSize)), [rows, 이쪽, pageSize]);
+    return {
+        pageRows,
+        /** Toolbar 의 pageSize 자리에 그대로 넣는다 */
+        pageSizeProps: { options: pageSizeOptions, value: pageSize, onChange: setPageSize },
+        /** Toolbar 의 pagination 자리에 그대로 넣는다 */
+        paginationProps: { page: 이쪽, total, onChange: setPage },
+        setPage,
+    };
+}
+/** 머리행 정렬 상태 — 같은 칸을 다시 누르면 방향이 뒤집힌다 @public */
+export function useTableSort() {
+    const [정렬, 정렬바꾸기] = useState(null);
+    const 누름 = useCallback((key) => {
+        정렬바꾸기(앞 => 앞?.key === key ? { key, asc: !앞.asc } : { key, asc: true });
+    }, []);
+    /** Table 의 field 하나에 붙일 것 — 라벨과 함께 쓴다 */
+    const 칸 = useCallback((label, key) => ({
+        label,
+        sortDir: 정렬?.key === key ? (정렬.asc ? 'asc' : 'desc') : null,
+        onClick: () => 누름(key),
+    }), [정렬, 누름]);
+    /* 쪽넘김에 그대로 건넨다 — 차례가 바뀌면 첫 쪽으로 돌아가게 */
+    return { 정렬, 칸 };
+}

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

@@ -0,0 +1,15 @@
+/** @public 토스트 종류 — 일반(성공/안내) vs 경고. */
+export type ToastType = 'normal' | 'warning';
+/**
+ * @public 토스트 상태 훅(메시지 + 종류) — 단어표/대립쌍표 검색 화면 등이 공용으로 쓴다.
+ * 여러 훅이 각자 갖고 있던 `{toastMessage, toastType} + set…` 관용구와 showWarning/showNormal 편의를 한곳으로 모은다.
+ */
+export declare function useToastState(defaultType?: ToastType): {
+    toastMessage: string;
+    toastType: ToastType;
+    toastKey: number;
+    showToast: (message: string, type: ToastType) => void;
+    showWarning: (message: string) => void;
+    showNormal: (message: string) => void;
+    clearToast: () => void;
+};

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

@@ -0,0 +1,29 @@
+'use client';
+import { useCallback, useState } from 'react';
+/**
+ * @public 토스트 상태 훅(메시지 + 종류) — 단어표/대립쌍표 검색 화면 등이 공용으로 쓴다.
+ * 여러 훅이 각자 갖고 있던 `{toastMessage, toastType} + set…` 관용구와 showWarning/showNormal 편의를 한곳으로 모은다.
+ */
+export function useToastState(defaultType = 'warning') {
+    const [toastMessage, setToastMessage] = useState('');
+    const [toastType, setToastType] = useState(defaultType);
+    /*
+     * 표시할 때마다 올라가는 번호. Toast 의 key 로 주면 **같은 문구를 연달아 알려도** 다시
+     * 뜬다 — 키가 없으면 리액트가 같은 요소로 보고 사라지던 애니메이션을 이어가, 두 번째
+     * 알림이 아예 안 보인다(같은 실패를 두 번 눌렀을 때가 그렇다).
+     *
+     * 이 값이 없어서 네 화면(문장훈련 플랜·고객 상세·회원 연결·단어표)이 이 훅을 못 쓰고
+     * `toastMsg + toastKey` 두 상태를 각자 손으로 들고 있었다. 여기에 얹어 한곳으로 모은다.
+     */
+    const [toastKey, setToastKey] = useState(0);
+    /** 종류를 함께 지정해 표시. */
+    const showToast = useCallback((message, type) => {
+        setToastType(type);
+        setToastMessage(message);
+        setToastKey(k => k + 1);
+    }, []);
+    const showWarning = useCallback((message) => showToast(message, 'warning'), [showToast]);
+    const showNormal = useCallback((message) => showToast(message, 'normal'), [showToast]);
+    const clearToast = useCallback(() => setToastMessage(''), []);
+    return { toastMessage, toastType, toastKey, showToast, showWarning, showNormal, clearToast };
+}

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

@@ -0,0 +1,7 @@
+/**
+ * 훈련 팝업 마운트~언마운트 시간을 기록합니다.
+ * 5초 미만 세션(잘못 열었다 닫은 경우)은 무시합니다.
+ *
+ * @public
+ */
+export default function useTrainingSessionLog(trainingType: string): void;

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

@@ -0,0 +1,26 @@
+'use client';
+import { useEffect } from 'react';
+import { logTrainingTime } from '../utils/trainingLogger';
+/**
+ * 훈련 팝업 마운트~언마운트 시간을 기록합니다.
+ * 5초 미만 세션(잘못 열었다 닫은 경우)은 무시합니다.
+ *
+ * @public
+ */
+export default function useTrainingSessionLog(trainingType) {
+    useEffect(() => {
+        if (!trainingType)
+            return; // 타입 미상이면 기록하지 않음
+        const startedAt = new Date();
+        return () => {
+            const endedAt = new Date();
+            if (endedAt.getTime() - startedAt.getTime() < 5000)
+                return;
+            logTrainingTime({
+                trainingType,
+                startedAt: startedAt.toISOString(),
+                endedAt: endedAt.toISOString(),
+            });
+        };
+    }, [trainingType]);
+}

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

@@ -0,0 +1,16 @@
+/**
+ * 훈련 유형 키 → 사람이 읽는 이름.
+ *
+ * 두 벌이 있다. **문장 쪽**(`CategoryData`)과 **단어 쪽 세부 유형**(`WORD_TRAINING_GROUPS`)이
+ * 서로 다른 곳에 적혀 있어서, 둘을 다 다루는 화면은 매번 합쳐 써야 한다. 훈련 현황이
+ * 그 합치는 일을 제 안에 갖고 있었는데 오답 구획도 같은 것이 필요해져, 여기로 옮겨 한 벌로 둔다.
+ *
+ * `all` 을 쓸 때도 **키를 못 찾으면 키 그대로 보여야 한다** — 새 유형이 생겼을 때 빈칸이
+ * 뜨면 무엇을 본 것인지 알 수가 없다. 부르는 쪽에서 `all[k] ?? k` 로 받는다.
+ */
+export declare function useTrainingTypeLabels(): {
+    /** 문장 훈련 유형만 — 차트 계열 이름 등에 쓴다 */
+    sentence: Record<string, string>;
+    /** 문장 + 단어 세부 유형 전부 */
+    all: Record<string, string>;
+};

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

@@ -0,0 +1,25 @@
+import { useMemo } from 'react';
+import { useTranslation } from 'react-i18next';
+import { translateTrainingTypes } from '../utils/CategoryData';
+import { WORD_TRAINING_GROUPS } from '../utils/wordTrainingGroups';
+/**
+ * 훈련 유형 키 → 사람이 읽는 이름.
+ *
+ * 두 벌이 있다. **문장 쪽**(`CategoryData`)과 **단어 쪽 세부 유형**(`WORD_TRAINING_GROUPS`)이
+ * 서로 다른 곳에 적혀 있어서, 둘을 다 다루는 화면은 매번 합쳐 써야 한다. 훈련 현황이
+ * 그 합치는 일을 제 안에 갖고 있었는데 오답 구획도 같은 것이 필요해져, 여기로 옮겨 한 벌로 둔다.
+ *
+ * `all` 을 쓸 때도 **키를 못 찾으면 키 그대로 보여야 한다** — 새 유형이 생겼을 때 빈칸이
+ * 뜨면 무엇을 본 것인지 알 수가 없다. 부르는 쪽에서 `all[k] ?? k` 로 받는다.
+ */
+export function useTrainingTypeLabels() {
+    const { t } = useTranslation();
+    return useMemo(() => {
+        const sentence = Object.fromEntries(translateTrainingTypes(t).map(x => [x.key, x.label]));
+        const all = { ...sentence };
+        WORD_TRAINING_GROUPS.flatMap(g => g.types).forEach(ty => {
+            all[ty.key] = t(`trainingType.${ty.key}.label`, { defaultValue: ty.label });
+        });
+        return { sentence, all };
+    }, [t]);
+}

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

@@ -0,0 +1,30 @@
+import type { VisitItem } from './useVisitHistory';
+export type VisitAllStatus = 'scheduled' | 'visited' | 'noShow';
+export type MergedVisit = {
+    item: VisitItem;
+    status: VisitAllStatus;
+};
+/**
+ * @public
+ */
+export declare const VAP_PAGE_SIZE_OPTIONS: {
+    value: string;
+    label: string;
+}[];
+/**
+ * 통합 방문 전체보기 팝업의 검색/필터/페이지네이션 상태를 관리하는 훅.
+ * `mergedVisits`(예정+완료+미방문)를 받아 파생 데이터를 계산.
+ */
+export declare function useVisitAllPanel(mergedVisits: MergedVisit[]): {
+    vapSearch: string;
+    setVapSearch: import("react").Dispatch<import("react").SetStateAction<string>>;
+    vapPageSize: string;
+    setVapPageSize: import("react").Dispatch<import("react").SetStateAction<string>>;
+    vapStatus: string;
+    setVapStatus: import("react").Dispatch<import("react").SetStateAction<string>>;
+    vapPage: number;
+    setVapPage: import("react").Dispatch<import("react").SetStateAction<number>>;
+    vapFiltered: MergedVisit[];
+    vapTotal: number;
+    vapPageItems: MergedVisit[];
+};

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

@@ -0,0 +1,43 @@
+'use client';
+import { useMemo, useState } from 'react';
+/**
+ * @public
+ */
+export const VAP_PAGE_SIZE_OPTIONS = [
+    { value: '10', label: '10개씩 보기' },
+    { value: '25', label: '25개씩 보기' },
+    { value: '50', label: '50개씩 보기' },
+    { value: '100', label: '100개씩 보기' },
+];
+/**
+ * 통합 방문 전체보기 팝업의 검색/필터/페이지네이션 상태를 관리하는 훅.
+ * `mergedVisits`(예정+완료+미방문)를 받아 파생 데이터를 계산.
+ */
+export function useVisitAllPanel(mergedVisits) {
+    const [vapSearch, setVapSearch] = useState('');
+    const [vapPageSize, setVapPageSize] = useState('25');
+    const [vapStatus, setVapStatus] = useState('all');
+    const [vapPage, setVapPage] = useState(1);
+    const vapFiltered = useMemo(() => mergedVisits.filter(({ item: v, status }) => {
+        if (vapSearch && !v.memo.includes(vapSearch))
+            return false;
+        if (vapStatus !== 'all' && status !== vapStatus)
+            return false;
+        return true;
+    }), [mergedVisits, vapSearch, vapStatus]);
+    const vapTotal = Math.max(1, Math.ceil(vapFiltered.length / Number(vapPageSize)));
+    // 필터/검색으로 결과가 줄면 현재 페이지가 총 페이지를 초과해 빈 화면이 됨 → 슬라이스 시 clamp
+    const vapPageItems = useMemo(() => {
+        const page = Math.min(vapPage, vapTotal);
+        return vapFiltered.slice((page - 1) * Number(vapPageSize), page * Number(vapPageSize));
+    }, [vapFiltered, vapPage, vapPageSize, vapTotal]);
+    return {
+        vapSearch, setVapSearch,
+        vapPageSize, setVapPageSize,
+        vapStatus, setVapStatus,
+        vapPage, setVapPage,
+        vapFiltered,
+        vapTotal,
+        vapPageItems,
+    };
+}

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

@@ -0,0 +1,38 @@
+export type VisitItem = {
+    year: string;
+    month: string;
+    day: string;
+    hour: string;
+    minute: string;
+    memo: string;
+    /** 서버(managed_visit) 실데이터로 채워진 항목의 실제 DB row id. 로컬로만 만든(더미/새로
+     *  추가한) 항목엔 없다 — 향후 서버 수정 API 연동 시 이 값으로 대상을 특정해야 한다
+     *  (연월일시분을 합친 합성 키는 실제 row id가 아니라 수정 대상 특정에 쓸 수 없다). */
+    id?: string;
+};
+/**
+ * @public
+ */
+export declare const today: () => {
+    year: string;
+    month: string;
+    day: string;
+};
+export declare function useVisitHistory(initialHistory?: VisitItem[]): {
+    visitHistory: VisitItem[];
+    visitForm: VisitItem;
+    setVisitForm: import("react").Dispatch<import("react").SetStateAction<VisitItem>>;
+    setVisit: (key: keyof VisitItem) => (value: string) => void;
+    selectedVisit: VisitItem | null;
+    setSelectedVisit: import("react").Dispatch<import("react").SetStateAction<VisitItem | null>>;
+    isEditingVisit: boolean;
+    setIsEditingVisit: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    editVisitForm: VisitItem;
+    setEditVisitForm: import("react").Dispatch<import("react").SetStateAction<VisitItem>>;
+    openVisitDetail: (item: VisitItem) => void;
+    handleVisitSave: (closeSubPopup?: () => void) => void;
+    handleVisitEditSave: () => void;
+    addVisit: (item: VisitItem) => void;
+    removeVisit: (item: VisitItem) => void;
+    revertVisitEdit: (original: VisitItem, edited: VisitItem) => void;
+};