@ihabdevteam/core 0.8.0

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

@@ -0,0 +1,184 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { cx } from '../utils/cx';
+import { MARKS, scoreKey, MARK_ICON, MARK_VARIANT } from './Word/wordTableScoring';
+import { useRef, useState, useEffect, useCallback, useMemo, Fragment, } from 'react';
+import { useTranslation } from 'react-i18next';
+import './WordTable.css';
+import Button from './Button';
+import Section from './Section';
+import DescriptionTooltip from './Tooltip/DescriptionTooltip';
+import { getTTSUrlResolver } from '../utils/ttsConfig';
+import { getImageResolver } from '../utils/imageConfig';
+import { getPronunciationResolver } from '../utils/pronunciationConfig';
+import { useWordImage } from '../hooks/useWordImage';
+import { WORD_TABLE_PAPER, gridFor, CUT_CLASS, POS_LABEL, WORD_TYPE_LABEL, expandSlashLabel, dotDashStyle, REF_W_BOTH, REF_W_TEXT_ONLY, REF_W_IMAGE_ONLY, REF_H_BOTH, REF_H_TEXT_ONLY, REF_H_IMAGE_ONLY, } from './wordTableLayout';
+import { useFitScale } from './useFitScale';
+// 외부(배럴·TodayPage·WordTableBlock 등) import 호환을 위해 재export
+/* 순수 함수(printWordTable·chunkItems)는 여기서 재수출하지 않는다 — 컴포넌트 파일이
+   컴포넌트 아닌 것을 내보내면 Fast Refresh 가 깨져, 이 파일을 고칠 때마다 화면 상태가
+   통째로 날아간다. 쓰는 쪽은 `wordTableLayout` 에서 바로 가져온다.
+   (상수 하나는 남긴다 — 규칙이 상수는 허용하고, 지우면 공개 API 가 바뀐다.) */
+export { WORD_TABLE_PAPER } from './wordTableLayout';
+// 모듈 레벨 — 단어표 안에는 WordCell이 다수 렌더되는데, 각자 자기 audio만 관리하면
+// 여러 셀을 빠르게 연달아 클릭했을 때 발음이 겹쳐 재생된다. 마지막으로 재생을 시작한
+// 인스턴스만 currentlyPlaying으로 추적해, 새 재생이 시작될 때 이전 것을 정지시킨다.
+let currentlyPlaying = null;
+function WordCell({ label, subLabel, colloquialLabel, homonum, showWord = true, showImage = true, showPronunciation = true, showColloquial = true, buttonSize = 40, wordInfo, }) {
+    const { t } = useTranslation();
+    const outerRef = useRef(null);
+    const infoRef = useRef(null);
+    const audioRef = useRef(null);
+    const [scale, setScale] = useState(1);
+    const [playing, setPlaying] = useState(false);
+    const [audioUrl, setAudioUrl] = useState('');
+    const [infoAnchor, setInfoAnchor] = useState(null);
+    // 발음(subLabel)이 없으면 단어로 표준발음 조회(앱 주입 resolver)
+    const pron = (subLabel && subLabel.length > 0) ? subLabel : (getPronunciationResolver()?.(label, homonum) ?? '');
+    const imageUrl = getImageResolver()?.(label, homonum) ?? '';
+    const { imgRef, loading: imgLoading, failed: imgFailed, onLoad: handleImgLoad, onError: handleImgError } = useWordImage(imageUrl);
+    const handleInfoEnter = useCallback(() => setInfoAnchor(infoRef.current?.getBoundingClientRect() ?? null), []);
+    const handleInfoLeave = useCallback(() => setInfoAnchor(null), []);
+    const infoTooltipItems = useMemo(() => {
+        if (!wordInfo)
+            return null;
+        const arr = [];
+        if (wordInfo.grade)
+            arr.push(`난이도: ${wordInfo.grade}등급`);
+        if (wordInfo.syllables)
+            arr.push(`음절 수: ${wordInfo.syllables}음절`);
+        // 축약 코드를 전체 표기로 — 복합값('명/관' → '명사/관형사')도 각각 펼친다(단어 관리 표와 동일 규칙).
+        if (wordInfo.pos)
+            arr.push(`품사: ${expandSlashLabel(wordInfo.pos, POS_LABEL)}`);
+        if (wordInfo.wordType)
+            arr.push(`유형: ${expandSlashLabel(wordInfo.wordType, WORD_TYPE_LABEL)}`);
+        return arr.length ? arr : null;
+    }, [wordInfo]);
+    useEffect(() => {
+        const resolver = getTTSUrlResolver();
+        const ttsText = pron || label;
+        if (!resolver || !ttsText)
+            return;
+        let cancelled = false;
+        Promise.resolve(resolver(ttsText)).then(url => { if (!cancelled && url)
+            setAudioUrl(url); });
+        return () => { cancelled = true; };
+    }, [pron, label]);
+    // 컴포넌트 언마운트 시 발음 재생 중단 — audioRef는 <audio> JSX가 아니라 new Audio()로
+    // 직접 만든 객체라 DOM에서 안 사라지므로, 재생 중에 팝업이 닫히는 등으로 언마운트되면
+    // pause() 없이는 화면이 사라진 뒤에도 계속 재생된다.
+    useEffect(() => () => {
+        audioRef.current?.pause();
+        if (currentlyPlaying?.audio === audioRef.current)
+            currentlyPlaying = null;
+    }, []);
+    const handlePlay = useCallback(async (e) => {
+        e.stopPropagation();
+        if (playing) {
+            audioRef.current?.pause();
+            setPlaying(false);
+            currentlyPlaying = null;
+            return;
+        }
+        if (!audioUrl)
+            return;
+        currentlyPlaying?.stop();
+        setPlaying(true);
+        try {
+            const audio = new Audio(audioUrl);
+            audioRef.current = audio;
+            const clearIfSelf = () => { setPlaying(false); if (currentlyPlaying?.audio === audio)
+                currentlyPlaying = null; };
+            currentlyPlaying = { audio, stop: () => { audio.pause(); clearIfSelf(); } };
+            audio.onended = clearIfSelf;
+            audio.onerror = clearIfSelf;
+            await audio.play();
+        }
+        catch {
+            setPlaying(false);
+            if (currentlyPlaying?.audio === audioRef.current)
+                currentlyPlaying = null;
+        }
+    }, [playing, audioUrl]);
+    const hasImage = showImage && !!imageUrl && !imgFailed;
+    const refW = hasImage && showWord ? REF_W_BOTH : hasImage ? REF_W_IMAGE_ONLY : REF_W_TEXT_ONLY;
+    const refH = hasImage && showWord ? REF_H_BOTH : hasImage ? REF_H_IMAGE_ONLY : REF_H_TEXT_ONLY;
+    useEffect(() => {
+        const el = outerRef.current;
+        if (!el)
+            return;
+        // ResizeObserver 가 없는 환경(구형 브라우저·SSR·테스트 러너)에서는 생성자 호출이
+        // 그대로 던져 렌더가 통째로 깨진다. 없으면 초기 배율(1)로 그대로 그린다
+        // (Popup·CrosswordGame·Tooltip 과 같은 처리).
+        if (typeof ResizeObserver === 'undefined')
+            return;
+        const obs = new ResizeObserver(([entry]) => {
+            const { width, height } = entry.contentRect;
+            setScale(Math.min(width / refW, height / refH));
+        });
+        obs.observe(el);
+        return () => obs.disconnect();
+    }, [refW, refH]);
+    return (_jsxs("div", { ref: outerRef, className: "word-table-cell", children: [_jsxs("div", { className: "word-table-cell__inner", style: { transform: `scale(${scale})` }, children: [hasImage && (_jsxs("div", { className: "word-table-cell__image-wrap", children: [imgLoading && _jsx("div", { className: "word-table-cell__spinner" }), _jsx("img", { ref: imgRef, className: "word-table-cell__image", src: imageUrl, alt: label, draggable: false, style: { opacity: imgLoading ? 0 : 1 }, onLoad: handleImgLoad, onError: handleImgError })] })), showWord && _jsx("span", { className: "word-table-cell__word h0", children: label }), showPronunciation && pron && _jsxs("span", { className: "word-table-cell__sub h3", children: ["[", pron, "]"] }), showColloquial && colloquialLabel && _jsxs("span", { className: "word-table-cell__colloquial h5", children: ["[", colloquialLabel, "]"] })] }), _jsxs("div", { className: "word-table-cell__play-button", "data-audio-src": audioUrl, children: [_jsx("span", { "data-play-state": "play", style: { display: playing ? 'none' : undefined }, children: _jsx(Button, { size: buttonSize, type: "dot", icon: "play", variant: "transparent-lightGray", useBorder: false, showTooltipInfo: t('common.play', '재생'), onClick: handlePlay }) }), _jsx("span", { "data-play-state": "pause", style: { display: playing ? undefined : 'none' }, children: _jsx(Button, { size: buttonSize, type: "dot", icon: "pause", useBorder: false, selected: true, showTooltipInfo: t('common.pause', '멈춤'), onClick: handlePlay }) })] }), wordInfo && (_jsxs("div", { ref: infoRef, className: "word-table-cell__info-button", onPointerEnter: handleInfoEnter, onPointerLeave: handleInfoLeave, 
+                // 이 div 자체는 포커스 대상이 아니지만 안의 Button이 포커스를 받으면
+                // focusin이 여기로 올라온다 — 그래서 래퍼에 걸어도 동작한다.
+                onFocus: handleInfoEnter, onBlur: handleInfoLeave, children: [_jsx(Button, { size: buttonSize, type: "dot", icon: "info", variant: "transparent-lightGray", useBorder: false, showTooltipInfo: false, 
+                        /* 아이콘만 있는 버튼이라 이름이 없으면 화면 낭독기가 "버튼"으로만 읽는다.
+                           한 표에 칸마다 하나씩 있어 열두 개가 다 "버튼"이 된다 — 어느 낱말의
+                           것인지 알 길이 없으므로 낱말을 이름에 넣는다. */
+                        ariaLabel: t('wordTable.wordInfo', '{{word}} 낱말 정보', { word: label }), onClick: (e) => e.stopPropagation() }), infoAnchor && infoTooltipItems && (_jsx(DescriptionTooltip, { anchorRect: infoAnchor, items: infoTooltipItems, showIndex: false }))] }))] }));
+}
+/**
+ * 단어표(표 디자인) — A4 종이를 컨테이너에 맞춰 축소(scale)하고,
+ * 칸 그리드와 단어 셀을 그린다. 컨트롤(필터·저장·인쇄)은 포함하지 않는다.
+ * 표시(items)·편집(editCells) 두 모드를 지원한다.
+ * @public
+ */
+export default function WordTable({ title, titleIcon, disc, className, orientation = 'landscape', contentTypes = ['이미지', '단어', '표준 발음'], cutLine = '표시', showOutline = true, showDivLine = true, items, editCells, count, activeCell = null, onActivateCell, onRemoveCell, onRemoveItem, onReorder, showFillerAdd = false, contentRef, buttonSize = 40, pageNumber, pageNumberPosition = 'right', fitHeight = false, scoring = false, marks, onMarkClick, scoreIndexOffset = 0, }) {
+    const clickMark = useCallback((cellIndex, clicked) => {
+        onMarkClick?.(scoreIndexOffset + cellIndex, clicked);
+    }, [onMarkClick, scoreIndexOffset]);
+    /* 칸 하나에 붙는 채점 표시. **대립쌍표는 한 칸이 낱말 둘이지만 시행은 한 번**이라
+       낱말이 아니라 칸에 매긴다(`wordTableScoring` 참고). */
+    const renderScore = (cellIndex, cellLabel) => {
+        const mark = marks?.[scoreKey(scoreIndexOffset + cellIndex)] ?? null;
+        return (
+        /* 세 단추를 늘 함께 그린다. 매기지 않은 칸은 통째로 숨어 있다가 마우스를 올리면
+           나타나고, 매긴 칸은 **고른 것만** 남는다(CSS 가 나머지를 감춘다). 그래야 표를
+           훑어 "어디를 어떻게 봤는지"가 한눈에 들어온다. */
+        _jsx("div", { className: cx('word-table-cell__score', mark ? 'word-table-cell__score--marked' : ''), children: MARKS.map(m => (_jsx("span", { className: cx('word-table-cell__score-slot', mark === m ? 'word-table-cell__score-slot--on' : ''), children: _jsx(Button, { size: buttonSize, type: "dot", icon: MARK_ICON[m], variant: mark === m ? MARK_VARIANT[m] : 'default', selected: mark === m, useBorder: false, showTooltipInfo: false, ariaLabel: t(`wordTable.scoring.${m}`, { word: cellLabel, defaultValue: `${cellLabel} ${m}` }), onClick: (e) => { e.stopPropagation(); clickMark(cellIndex, m); } }) }, m))) }));
+    };
+    const { t } = useTranslation();
+    const isEdit = editCells !== undefined;
+    // 드래그 상태(표시 모드 재정렬)
+    const dragIndex = useRef(null);
+    const [dragOver, setDragOver] = useState(null);
+    const { width, height } = WORD_TABLE_PAPER[orientation];
+    // 스케일러 — 용지(width 고정)를 컨테이너 폭에 맞춰 축소 + 가운데 정렬. fitHeight면 높이도 함께 맞춘다.
+    const { scalerRef, scale, offset } = useFitScale(width, fitHeight ? height : undefined);
+    const dataLen = isEdit ? (editCells?.length ?? 0) : (items?.length ?? 0);
+    const cellCount = Math.max(count ?? dataLen, 1);
+    const { cols, rows } = gridFor(orientation, cellCount);
+    const show = {
+        word: contentTypes.length === 0 || contentTypes.includes('단어'),
+        image: contentTypes.length === 0 || contentTypes.includes('이미지'),
+        pron: contentTypes.length === 0 || contentTypes.includes('표준 발음'),
+        colloq: contentTypes.length === 0 || contentTypes.includes('구어체 발음'),
+    };
+    const hasPairs = isEdit
+        ? (editCells ?? []).some(c => c !== null && c.length > 1)
+        : (items ?? []).some(item => item.words.length > 1);
+    const contentClass = cx('word-table-block__content', CUT_CLASS[cutLine], showOutline && 'word-table-block__content--outline', showDivLine && hasPairs && 'word-table-block__content--div-line');
+    // 빈칸(추가버튼)은 스케일 역보정으로 실제 크기 유지
+    const counterScale = { transform: `scale(${1 / scale})`, transformOrigin: 'center center' };
+    const grid = (_jsx("div", { ref: scalerRef, className: "word-table__scaler", style: { height: height * scale }, children: _jsx("div", { className: cx('word-table', className), style: { width, height, transform: `scale(${scale})`, transformOrigin: 'top left', marginLeft: offset }, children: _jsxs("div", { ref: contentRef, className: contentClass, style: { gridTemplateColumns: `repeat(${cols}, 1fr)`, gridTemplateRows: `repeat(${rows}, 1fr)` }, children: [isEdit ? (_jsx(_Fragment, { children: (editCells ?? []).map((cell, i) => (_jsx("div", { className: cx('word-table-block__edit-cell', cell ? 'word-table-block__edit-cell--filled' : 'word-table-block__edit-cell--empty', activeCell === i ? 'word-table-block__edit-cell--active' : ''), style: dotDashStyle(i, cols, rows, cutLine), children: cell ? (_jsxs(_Fragment, { children: [cell.map((e, wi) => (_jsxs(Fragment, { children: [wi > 0 && _jsx("div", { className: "word-table-block__pair-divider" }), _jsx(WordCell, { label: e.word, subLabel: e.pronunciation, homonum: e.homonum, showWord: show.word, showImage: show.image, showPronunciation: show.pron, showColloquial: show.colloq, buttonSize: buttonSize })] }, wi))), scoring && renderScore(i, cell.map(e => e.word).join(' / ')), onRemoveCell && (_jsx("div", { className: "word-table-block__card-close", children: _jsx(Button, { size: buttonSize, type: "dot", icon: "x", variant: "transparent-lightGray", useBorder: false, showTooltipInfo: cell.length > 1 ? t('wordPrint.removePair', '대립쌍 빼기') : t('wordPrint.removeWord', '단어 빼기'), ariaLabel: cell.length > 1 ? t('wordPrint.removePair', '대립쌍 빼기') : t('wordPrint.removeWord', '단어 빼기'), onClick: () => onRemoveCell(i) }) }))] })) : (onActivateCell && (_jsx("div", { style: counterScale, children: _jsx(Button, { size: "48", type: "bar", icon: "plus", label: t('wordTable.addWord', '추가하기'), onClick: () => onActivateCell(i) }) }))) }, i))) })) : (_jsxs(_Fragment, { children: [(items ?? []).map((item, index) => (_jsxs("div", { className: `word-table-block__card${onReorder ? ' word-table-block__card--draggable' : ''}${dragOver === index ? ' word-table-block__card--drag-over' : ''}`, style: dotDashStyle(index, cols, rows, cutLine), draggable: !!onReorder, onDragStart: onReorder ? () => { dragIndex.current = index; } : undefined, onDragOver: onReorder ? (e) => { e.preventDefault(); setDragOver(index); } : undefined, onDragLeave: onReorder ? () => setDragOver(null) : undefined, onDrop: onReorder ? (e) => { e.preventDefault(); if (dragIndex.current !== null && dragIndex.current !== index) {
+                                    onReorder(dragIndex.current, index);
+                                } ; dragIndex.current = null; setDragOver(null); } : undefined, onDragEnd: onReorder ? () => { dragIndex.current = null; setDragOver(null); } : undefined, children: [item.words.map((w, i) => (_jsxs(Fragment, { children: [i > 0 && _jsx("div", { className: "word-table-block__pair-divider" }), _jsx(WordCell, { label: w.label, subLabel: w.subLabel, colloquialLabel: w.colloquialLabel, homonum: w.homonum, showWord: show.word, showImage: show.image, showPronunciation: show.pron, showColloquial: show.colloq, buttonSize: buttonSize, wordInfo: (w.grade || w.syllables != null || w.pos || w.wordType) ? { grade: w.grade, syllables: w.syllables, pos: w.pos, wordType: w.wordType } : undefined })] }, i))), scoring && renderScore(index, item.words.map(w => w.label).join(' / ')), onRemoveItem && (_jsx("div", { className: "word-table-block__card-close", children: _jsx(Button, { size: buttonSize, type: "dot", icon: "x", variant: "transparent-lightGray", useBorder: false, showTooltipInfo: item.words.length > 1 ? t('wordPrint.removePair', '대립쌍 빼기') : t('wordPrint.removeWord', '단어 빼기'), ariaLabel: item.words.length > 1 ? t('wordPrint.removePair', '대립쌍 빼기') : t('wordPrint.removeWord', '단어 빼기'), onClick: () => onRemoveItem(item.id) }) }))] }, item.id))), Array.from({ length: Math.max(0, cols * rows - (items?.length ?? 0)) }).map((_, i) => {
+                                const isWithinCount = (items?.length ?? 0) + i < cellCount;
+                                return (_jsx("div", { className: "word-table-block__card word-table-block__card--filler", children: showFillerAdd && onActivateCell && isWithinCount && (_jsx("div", { style: counterScale, children: _jsx(Button, { size: buttonSize, type: "bar", icon: "plus", label: t('wordTable.addWord', '추가하기'), onClick: () => onActivateCell((items?.length ?? 0) + i) }) })) }, `filler-${i}`));
+                            })] })), pageNumber && pageNumberPosition !== 'none' && (_jsx("span", { className: `word-table__page-number body-3 word-table__page-number--${pageNumberPosition}`, children: t('wordTable.filter.pageIndicator', { current: pageNumber.current, total: pageNumber.total }) }))] }) }) }));
+    if (title != null || titleIcon || disc) {
+        return (_jsx(Section, { type: "page", icon: titleIcon, title: title, disc: disc, className: cx('word-table-block', className), children: grid }));
+    }
+    return grid;
+}

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

@@ -0,0 +1,48 @@
+/**
+ * barChartData.ts
+ * BarChart의 순수 데이터 계층 — 날짜→월/주/일 막대 데이터 집계 (React 무관).
+ */
+/** 막대 하나의 데이터 — a/b 두 계열. a === -1 이면 미래(데이터 없음)로 표시하지 않음.
+ *  parts: 다계열 stacked용 계열별 값(있으면 a는 합계로 사용). */
+export interface BarData {
+    label: string;
+    sublabel?: string;
+    a: number;
+    b: number;
+    rawA?: number;
+    rawB?: number;
+    isToday?: boolean;
+    parts?: number[];
+}
+/** 한 구간(월 등)의 주별/일별 막대 데이터 묶음 */
+export type MonthBarData = {
+    weekly: BarData[];
+    daily: BarData[];
+};
+/** 날짜별 카운트 포인트 — a/b 2계열 또는 parts(다계열 stacked, a는 합계) */
+export interface ChartPoint {
+    date: Date;
+    a: number;
+    b: number;
+    parts?: number[];
+}
+/** 해당 월(0-based)의 첫 월요일 날짜(1~7). 예: 2026-05(금요일 시작) → 4 */
+export declare function firstMondayOfMonth(year: number, month0: number): number;
+/** 오늘이 속한 (월키, 주값) 계산 — 진입 시 기본 선택을 오늘 기준으로 맞춤.
+ *  월요일 시작 버킷 기준이며, 첫 월요일 이전 날짜는 이전 달 마지막 주에 속한다. */
+export declare function todayWeekValue(): {
+    monthKey: string;
+    value: string;
+};
+/**
+ * 날짜별 포인트들을 'YYYY년 M월' 키의 주별/일별 막대 데이터로 집계.
+ * 현재 월의 미래 날짜(데이터 없음)는 a = -1 로 표시해 막대를 렌더하지 않는다.
+ */
+export declare function buildMonthChartData(points: ChartPoint[]): Record<string, MonthBarData>;
+export declare const MONTH_OPTIONS: {
+    value: string;
+    label: string;
+    year: number;
+    month: number;
+}[];
+export declare const KO_ORD: string[];

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

@@ -0,0 +1,111 @@
+/**
+ * barChartData.ts
+ * BarChart의 순수 데이터 계층 — 날짜→월/주/일 막대 데이터 집계 (React 무관).
+ */
+/** 해당 월(0-based)의 첫 월요일 날짜(1~7). 예: 2026-05(금요일 시작) → 4 */
+export function firstMondayOfMonth(year, month0) {
+    const dow = new Date(year, month0, 1).getDay(); // 0=일 … 6=토
+    return 1 + ((8 - (dow === 0 ? 7 : dow)) % 7);
+}
+/** 오늘이 속한 (월키, 주값) 계산 — 진입 시 기본 선택을 오늘 기준으로 맞춤.
+ *  월요일 시작 버킷 기준이며, 첫 월요일 이전 날짜는 이전 달 마지막 주에 속한다. */
+export function todayWeekValue() {
+    const now = new Date();
+    let y = now.getFullYear(), m0 = now.getMonth(), date = now.getDate();
+    if (date < firstMondayOfMonth(y, m0)) {
+        const prevLast = new Date(y, m0, 0); // 이전 달 마지막 날
+        y = prevLast.getFullYear();
+        m0 = prevLast.getMonth();
+        date = prevLast.getDate();
+    }
+    const week = Math.floor((date - firstMondayOfMonth(y, m0)) / 7);
+    const monthKey = `${y}년 ${m0 + 1}월`;
+    return { monthKey, value: `${monthKey}#${week}` };
+}
+/**
+ * 날짜별 포인트들을 'YYYY년 M월' 키의 주별/일별 막대 데이터로 집계.
+ * 현재 월의 미래 날짜(데이터 없음)는 a = -1 로 표시해 막대를 렌더하지 않는다.
+ */
+export function buildMonthChartData(points) {
+    const now = new Date();
+    const curKey = `${now.getFullYear()}년 ${now.getMonth() + 1}월`;
+    const byMonth = new Map();
+    byMonth.set(curKey, []);
+    for (const p of points) {
+        if (isNaN(p.date.getTime()))
+            continue;
+        const key = `${p.date.getFullYear()}년 ${p.date.getMonth() + 1}월`;
+        if (!byMonth.has(key))
+            byMonth.set(key, []);
+        byMonth.get(key).push(p);
+    }
+    const result = {};
+    for (const [key, pts] of byMonth) {
+        const m = key.match(/^(\d+)년 (\d+)월$/);
+        if (!m)
+            continue;
+        const year = Number(m[1]);
+        const month = Number(m[2]) - 1;
+        const daysInMonth = new Date(year, month + 1, 0).getDate();
+        const isCurMonth = year === now.getFullYear() && month === now.getMonth();
+        const today = now.getDate();
+        const partsLen = pts.reduce((n, p) => Math.max(n, p.parts?.length ?? 0), 0);
+        const dayA = new Array(daysInMonth + 1).fill(0);
+        const dayB = new Array(daysInMonth + 1).fill(0);
+        const dayParts = Array.from({ length: daysInMonth + 1 }, () => new Array(partsLen).fill(0));
+        for (const p of pts) {
+            const d = p.date.getDate();
+            dayA[d] += p.a;
+            dayB[d] += p.b;
+            if (p.parts)
+                for (let k = 0; k < partsLen; k++)
+                    dayParts[d][k] += p.parts[k] ?? 0;
+        }
+        const daily = [];
+        for (let d = 1; d <= daysInMonth; d++) {
+            const isFuture = isCurMonth && d > today;
+            daily.push({
+                label: String(d),
+                a: isFuture && dayA[d] === 0 && dayB[d] === 0 ? -1 : dayA[d],
+                b: dayB[d],
+                ...(partsLen ? { parts: dayParts[d] } : {}),
+            });
+        }
+        // 월요일 시작 — 그 달의 '첫 월요일'부터 7일 단위로 버킷. 첫 월요일 이전 날짜는
+        // 이전 달의 마지막(걸침) 주에 속하므로 이 달에서는 제외한다.
+        const weekly = [];
+        for (let start = firstMondayOfMonth(year, month); start <= daysInMonth; start += 7) {
+            const end = Math.min(start + 6, daysInMonth);
+            let a = 0;
+            let b = 0;
+            const wParts = new Array(partsLen).fill(0);
+            for (let d = start; d <= end; d++) {
+                a += dayA[d];
+                b += dayB[d];
+                for (let k = 0; k < partsLen; k++)
+                    wParts[k] += dayParts[d][k];
+            }
+            weekly.push({ label: `${weekly.length + 1}주`, sublabel: `[${start}일~${end}일]`, a, b, ...(partsLen ? { parts: wParts } : {}) });
+        }
+        result[key] = { weekly, daily };
+    }
+    return result;
+}
+// 드롭다운에 노출할 월 옵션 (2024년 1월 ~ 현재, 최신순)
+function genMonthOptions() {
+    const now = new Date();
+    const curY = now.getFullYear();
+    const curM = now.getMonth() + 1;
+    const opts = [];
+    for (let y = 2024; y <= curY; y++) {
+        const end = y === curY ? curM : 12;
+        for (let m = 1; m <= end; m++) {
+            const v = `${y}년 ${m}월`;
+            opts.push({ value: v, label: v, year: y, month: m });
+        }
+    }
+    return opts.reverse();
+}
+export const MONTH_OPTIONS = genMonthOptions();
+// 한글 서수(주차) — '첫째주', '둘째주' …
+export const KO_ORD = ['첫째', '둘째', '셋째', '넷째', '다섯째', '여섯째', '일곱째'];

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

@@ -0,0 +1,82 @@
+import type { MonthBarData } from './barChartData';
+/** @public */
+export interface BarChartControl {
+    period: 'month' | 'week';
+    setPeriod: (p: 'month' | 'week') => void;
+    range: string;
+    setRange: (v: string) => void;
+    activeOptions: {
+        value: string;
+        label: string;
+    }[];
+    activeIdx: number;
+    handlePrev: () => void;
+    handleNext: () => void;
+    periodOptions: {
+        key: string;
+        label: string;
+    }[];
+    monthRange: string;
+    weekRange: string;
+    weekRanges: {
+        value: string;
+        monthKey: string;
+        year: number;
+        month: number;
+        week: number;
+    }[];
+    DOW: string[];
+}
+/** 시맨틱 사이즈 — 차트 캔버스 높이·막대 너비 프리셋 */
+export type BarChartSize = 'small' | 'medium' | 'large';
+export interface BarChartProps {
+    /**
+     * 크기 — 'small'|'medium'|'large' (기본: 'medium'). 캔버스 크기뿐 아니라 정보량도 함께 조절한다.
+     *  - small:  대시보드 작은 그리드용 블럭. 컨트롤(headRight)만 생략하고 total/legend는 medium과 동일하게 유지
+     *  - medium: 표준 형태(제목 + 컨트롤 + total + legend). 2~3열 그리드에 inline 배치하는 기본값
+     *  - large:  카드가 가로 폭을 거의 100% 차지(1열). medium과 정보량은 동일, 캔버스만 더 크게
+     */
+    size?: BarChartSize;
+    /** 섹션 제목 i18n 키 */
+    titleKey: string;
+    /** 구간(월) 키 → 주별/일별 데이터 */
+    data: Record<string, MonthBarData>;
+    colorA: string;
+    /** 계열 B 색상. 미지정 시 단일 계열(A) 차트 */
+    colorB?: string;
+    /** 계열 A/B 레이블 i18n 키. labelBKey 미지정 시 단일 계열 */
+    labelAKey: string;
+    labelBKey?: string;
+    /** 선택된 구간의 합계(a+b)를 헤더 아래 히어로로 표시 */
+    showTotal?: boolean;
+    /** 합계 단위 i18n 키 (예: 'trainingStatus.weekly.unit' → '회') */
+    totalUnitKey?: string;
+    /** rate 모드 합계 라벨 i18n 키 (예: '진행률 평균'). 미지정 시 labelAKey 사용. 라벨이 숫자 앞에 표시됨 (size='small'에서는 생략됨) */
+    totalLabelKey?: string;
+    /** 외부에서 공유하는 기간 컨트롤. 지정 시 내부 컨트롤 대신 사용 */
+    control?: BarChartControl;
+    /** 헤더의 기간 컨트롤 UI 숨김 (control을 외부 Toolbar 등에 둘 때) */
+    hideControls?: boolean;
+    /** 완료율(%) 모드 — a=완료수, b=전체수로 보고 각 막대를 a/b×100(%)로 렌더. 합계도 비율 */
+    rate?: boolean;
+    /** y축 최대를 데이터 최댓값으로 (10 단위 올림 없이). 가장 큰 막대가 차트 상단에 닿음 */
+    tightMax?: boolean;
+    /** 평균 모드 — 합계 대신 경과한 일별 a의 평균을 헤더에 표시(진행률처럼 stacked 라벨). */
+    avgMode?: boolean;
+    /** 헤더 합계/평균 값 포맷터(예: 분 → 'X시간 Y분'). 지정 시 단위 대신 포맷 문자열 표시. */
+    totalFormat?: (n: number) => string;
+    /** 다계열(stacked) 정의 — data의 parts[index]와 1:1. 지정 시 막대를 계열별로 쌓고 범례도 계열별. */
+    series?: {
+        label: string;
+        color: string;
+    }[];
+    /** 로딩 중 — 차트 영역에 스피너 표시(헤더/레이아웃은 유지) */
+    loading?: boolean;
+    /** 지정 시 헤더 우측에 '상세보기' 버튼 표시 → 클릭 콜백 */
+    onDetail?: () => void;
+}
+/** 현재 컨트롤 선택(주/월)의 날짜 범위 — 상세보기(기간별 리스트)용 */
+export declare function getControlDateRange(control: BarChartControl): {
+    from: Date;
+    to: Date;
+};

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

@@ -0,0 +1,22 @@
+import { firstMondayOfMonth } from './barChartData';
+/** 현재 컨트롤 선택(주/월)의 날짜 범위 — 상세보기(기간별 리스트)용 */
+export function getControlDateRange(control) {
+    if (control.period === 'month') {
+        const m = control.monthRange.match(/^(\d+)년 (\d+)월$/);
+        const now = new Date();
+        const y = m ? Number(m[1]) : now.getFullYear();
+        const mo = m ? Number(m[2]) : now.getMonth() + 1;
+        return { from: new Date(y, mo - 1, 1, 0, 0, 0), to: new Date(y, mo, 0, 23, 59, 59) };
+    }
+    const opt = control.weekRanges.find(o => o.value === control.weekRange);
+    if (!opt) {
+        const n = new Date();
+        return { from: n, to: n };
+    }
+    const firstMon = firstMondayOfMonth(opt.year, opt.month - 1);
+    const monday = new Date(opt.year, opt.month - 1, firstMon + opt.week * 7, 0, 0, 0);
+    const sunday = new Date(monday);
+    sunday.setDate(monday.getDate() + 6);
+    sunday.setHours(23, 59, 59);
+    return { from: monday, to: sunday };
+}

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

@@ -0,0 +1,102 @@
+import type { MouseEvent, ReactNode } from 'react';
+/** @public */
+export type ButtonVariant = 'default' | 'main' | 'sub' | 'transparent-white' | 'transparent-gray' | 'transparent-lightGray' | 'danger' | 'disabled-faded' | (string & {});
+/** @public */
+export type ButtonLayoutType = 'bar' | 'dot';
+/**
+ * 버튼 모서리 형태.
+ * - `'rounded'` — 살짝 둥근 모서리 (8px)
+ * - `'pill'`    — 완전히 둥근 pill/캡슐 형태 (9999px)
+ * @public
+ */
+export type ButtonShape = 'rounded' | 'pill';
+/** @public */
+export interface ButtonProps {
+    /**
+     * 크기. 숫자는 CSS 의 크기 사다리(.button24 … .button72)와 짝을 이룬다 — **사다리에
+     * 없는 숫자를 넣으면 그 버튼은 크기·모서리 규칙을 하나도 못 받는다.**
+     *
+     * 목록이 사실과 두 군데 어긋나 있었다. 72 는 CSS 에 있는데 목록에 없었고, 52 는
+     * 목록에도 CSS 에도 없는데 BottomNav 가 쓰고 있었다(그쪽은 자체 클래스가 !important
+     * 로 크기를 다시 잡아 겉으로는 멀쩡했다). 둘 다 사실에 맞춘다 — 52 는 CSS 에 칸을
+     * 만들어 주고, 72 는 목록에 더한다.
+     *
+     * `(number & {})` · `(string & {})` 을 남겨 둔 이유는, 지금 저장소에 size="56" 처럼
+     * 문자열로 넘기는 자리가 열한 곳, 변수로 넘기는 자리가 여덟 곳 있어서다. 그걸 다
+     * 정리하면 이 탈출구를 없애 오타를 타입이 막게 할 수 있다 — 따로 판단이 필요하다.
+     */
+    size?: 24 | 28 | 32 | 40 | 48 | 52 | 56 | 72 | 'Keyboard' | 'Word' | (number & {}) | (string & {});
+    /** 레이아웃 타입. 기본값은 label/icon 유무에 따라 자동 결정됩니다. */
+    type?: ButtonLayoutType;
+    /**
+     * DOM 의 button type 속성. `type` 은 레이아웃 종류라 이름이 겹쳐 따로 둔다.
+     * 폼 안에서는 지정하지 않으면 브라우저 기본값인 'submit' 으로 동작한다.
+     */
+    htmlType?: 'button' | 'submit' | 'reset';
+    /**
+     * 지정하면 <button> 대신 <a> 로 렌더한다. 겉모습은 동일하고 링크 의미(새 창·
+     * 우클릭·복사)를 지킨다. disabled 상태에서는 링크를 걷어내고 비활성 표시만 남긴다.
+     */
+    href?: string;
+    /** href 와 함께 쓴다. */
+    target?: string;
+    rel?: string;
+    icon?: ReactNode | string;
+    rightIcon?: ReactNode | string;
+    /**
+     * 버튼에 표시할 텍스트/노드입니다.
+     * `children`이 함께 전달된 경우 `label`이 우선합니다.
+     */
+    label?: ReactNode | ReactNode[];
+    /**
+     * 라벨 옆에 붙는 강조 숫자(예: "말귀 스탠다드 3", "활성 4"). 기본색은 `--color-main`이며,
+     * 버튼이 선택된 상태(`is-selected`/`aria-pressed`)이거나 `variant="main"`이면 자동으로 흰색이 됩니다.
+     * 라벨-숫자 간격은 컴포넌트가 고정으로 관리합니다(직접 공백을 넣지 마세요).
+     */
+    count?: ReactNode;
+    subLabel?: ReactNode | ReactNode[];
+    /**
+     * `label` prop 대신 JSX children으로 텍스트를 전달할 수 있습니다.
+     * `label`이 있으면 `label`이 우선합니다.
+     * @example <Button variant="main">시작</Button>
+     */
+    children?: ReactNode;
+    ariaLabel?: string;
+    variant?: ButtonVariant;
+    align?: 'center' | 'left' | 'right' | 'grid';
+    selected?: boolean;
+    toggleable?: boolean;
+    disabled?: boolean;
+    /** label을 숨기려면 false로 설정 */
+    useLabel?: boolean;
+    useBorder?: boolean;
+    useBG?: boolean;
+    /** disabled 시 버튼을 배경색으로 가리는 스타일 */
+    useDisabledCovered?: boolean;
+    /** disabled 시 버튼을 완전히 투명하게 하는 스타일 */
+    useDisabledInvisible?: boolean;
+    width?: number | string;
+    minWidth?: number | string;
+    onClick?: (e: MouseEvent<HTMLButtonElement>) => void;
+    /** disabled 상태에서도 클릭 이벤트를 수신할 핸들러 */
+    onDisabledClick?: (e: MouseEvent<HTMLButtonElement>) => void;
+    showTooltipInfo?: boolean | string;
+    tooltipInfoText?: ReactNode | null;
+    /** 지정하면 InfoTooltip(한 줄 텍스트) 대신 DescriptionTooltip(제목+목록)을 호버/포커스 시 보여준다 */
+    tooltipDescription?: {
+        title?: string;
+        items: string[];
+    } | null;
+    iconSize?: 'small' | 'medium' | 'large';
+    iconColor?: string;
+    /**
+     * 버튼 모서리 형태. 기본값: `'rounded'`
+     * - `'rounded'` — 살짝 둥근 모서리 (12px)
+     * - `'pill'`    — 완전히 둥근 pill 형태 (9999px)
+     */
+    shape?: ButtonShape;
+    /** variant 색상을 커스텀 색상으로 덮어씁니다 (hex, rgb, CSS variable 모두 가능) */
+    color?: string;
+    className?: string;
+    [k: string]: unknown;
+}

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,9 @@
+/**
+ * 격자 칸 목록을 **칸 단위로** 쪼갠다.
+ *
+ * 그냥 빈칸으로 쪼개면 `minmax(120px, 1fr)` 이 세 조각(`minmax(120px,` · `1fr)`)으로
+ * 갈려 그 뒤 칸의 짝이 통째로 밀린다 — 폭을 저장해 둔 표에서 `resizable: false` 인
+ * 칸(체크박스 등)이 엉뚱한 값을 받고, fit 모드의 px/fr 판단도 어긋난다.
+ * 괄호 안의 빈칸은 건너뛴다.
+ */
+export declare function splitTrackList(template?: string): string[];

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

@@ -0,0 +1,32 @@
+/**
+ * 격자 칸 목록을 **칸 단위로** 쪼갠다.
+ *
+ * 그냥 빈칸으로 쪼개면 `minmax(120px, 1fr)` 이 세 조각(`minmax(120px,` · `1fr)`)으로
+ * 갈려 그 뒤 칸의 짝이 통째로 밀린다 — 폭을 저장해 둔 표에서 `resizable: false` 인
+ * 칸(체크박스 등)이 엉뚱한 값을 받고, fit 모드의 px/fr 판단도 어긋난다.
+ * 괄호 안의 빈칸은 건너뛴다.
+ */
+export function splitTrackList(template) {
+    if (!template)
+        return [];
+    const out = [];
+    let 깊이 = 0;
+    let 조각 = '';
+    for (const c of template.trim()) {
+        if (c === '(')
+            깊이++;
+        else if (c === ')')
+            깊이--;
+        if (/\s/.test(c) && 깊이 === 0) {
+            if (조각) {
+                out.push(조각);
+                조각 = '';
+            }
+            continue;
+        }
+        조각 += c;
+    }
+    if (조각)
+        out.push(조각);
+    return out;
+}

package/dist/packages/core/src/components/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>;