@ihabdevteam/core 0.8.0

package/dist/packages/core/src/components/Word/WordTableThumbnail.js

@@ -0,0 +1,21 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from '../../utils/cx';
+import { Fragment } from 'react';
+import './WordTableThumbnail.css';
+/**
+ * @public 단어표 내용 미니 미리보기(그리드 썸네일).
+ * 단어표 불러오기 팝업·나의 단어표 카드 등에서 공유하는 '문서형' 미리보기.
+ */
+export default function WordTableThumbnail({ items, className }) {
+    const n = items.length;
+    // 3개 이하는 세로 1열(빈칸 없이 3개가 세로로), 4개 이상은 2열
+    const cols = n <= 3 ? 1 : 2;
+    const rows = Math.ceil(n / cols) || 1;
+    const total = cols * rows;
+    return (_jsx("div", { className: cx('word-table-thumb', className), style: { gridTemplateColumns: `repeat(${cols}, 1fr)` }, children: Array.from({ length: total }, (_, i) => {
+            const item = items[i];
+            if (!item)
+                return _jsx("div", { className: "word-table-thumb__cell word-table-thumb__cell--empty" }, i);
+            return (_jsx("div", { className: "word-table-thumb__cell", children: (item.words.length ? item.words : [{ label: item.id }]).map((w, wi) => (_jsxs(Fragment, { children: [wi > 0 && _jsx("span", { className: "word-table-thumb__divider" }), _jsx("span", { className: "word-table-thumb__word body-3", children: w.label })] }, wi))) }, i));
+        }) }));
+}

package/dist/packages/core/src/components/Word/generatedDraft.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 자동으로 만든 것을 **저장하기 전에 손보는** 규칙.
+ *
+ * 지금까지는 누르면 곧바로 만들어졌다. 그런데 자동 생성은 **틀릴 수 있고**, 무엇보다
+ * 치료사가 "이건 좋은데 저건 아니다" 를 안다 — 그 판단을 넣을 자리가 없었다.
+ * 만들어 놓고 고치게 하면 지운 것이 기록에 남고 목록이 지저분해진다. 만들기 **전에** 고른다.
+ *
+ * 화면은 없다. 무엇을 붙들고 무엇을 다시 뽑을지만 안다.
+ */
+/** 초안 한 줄 — 무엇이든 담을 수 있게 값은 바깥에서 준다. */
+export interface DraftItem<T> {
+    /** 같은 것을 두 번 담지 않으려는 열쇠(낱말·세트 uuid 등) */
+    key: string;
+    value: T;
+    /** 고정 — 다시 뽑아도 이 자리는 그대로 둔다 */
+    pinned: boolean;
+}
+/** 값들을 초안으로 만든다(처음엔 아무것도 고정돼 있지 않다). */
+export declare function toDraft<T>(values: readonly T[], keyOf: (v: T) => string): DraftItem<T>[];
+/** 한 줄의 고정을 뒤집는다. */
+export declare function togglePin<T>(draft: readonly DraftItem<T>[], key: string): DraftItem<T>[];
+/** 한 줄을 뺀다. */
+export declare function removeItem<T>(draft: readonly DraftItem<T>[], key: string): DraftItem<T>[];
+/**
+ * **고정한 것은 두고 나머지만 다시 뽑는다.**
+ *
+ * 새로 받은 후보에서 **이미 고정된 것과 겹치는 것은 뺀다** — 안 그러면 같은 낱말이
+ * 두 줄이 되고, 그중 하나만 고정된 이상한 상태가 된다.
+ *
+ * 자리 수는 원래 만큼 채우되, 후보가 모자라면 **모자란 대로 둔다.** 억지로 채우려고
+ * 고정한 것을 밀어내면 사람이 고른 것을 시스템이 지우는 셈이다.
+ *
+ * 길이는 아래 마지막 `map` 이 원래 초안을 훑는 것으로 이미 묶인다 — 자리 수를 세는
+ * `break` 는 **정확성이 아니라 효율**이다(후보가 수백 개일 때 다 훑지 않으려는 것).
+ * 돌연변이로 확인했다: 그 줄을 없애도 결과가 같다.
+ */
+export declare function regenerateUnpinned<T>(draft: readonly DraftItem<T>[], candidates: readonly T[], keyOf: (v: T) => string): DraftItem<T>[];
+/** 저장할 값들 — 화면에 보이는 차례 그대로. */
+export declare function draftValues<T>(draft: readonly DraftItem<T>[]): T[];

package/dist/packages/core/src/components/Word/generatedDraft.js

@@ -0,0 +1,69 @@
+/**
+ * 자동으로 만든 것을 **저장하기 전에 손보는** 규칙.
+ *
+ * 지금까지는 누르면 곧바로 만들어졌다. 그런데 자동 생성은 **틀릴 수 있고**, 무엇보다
+ * 치료사가 "이건 좋은데 저건 아니다" 를 안다 — 그 판단을 넣을 자리가 없었다.
+ * 만들어 놓고 고치게 하면 지운 것이 기록에 남고 목록이 지저분해진다. 만들기 **전에** 고른다.
+ *
+ * 화면은 없다. 무엇을 붙들고 무엇을 다시 뽑을지만 안다.
+ */
+/** 값들을 초안으로 만든다(처음엔 아무것도 고정돼 있지 않다). */
+export function toDraft(values, keyOf) {
+    const out = [];
+    const 본것 = new Set();
+    for (const v of values) {
+        const key = keyOf(v);
+        /* 같은 열쇠가 두 번 오면 한 번만 담는다 — 초안에 같은 줄이 둘이면 고정·빼기가
+           어느 것에 걸린 것인지 사람이 알 수 없다. */
+        if (본것.has(key))
+            continue;
+        본것.add(key);
+        out.push({ key, value: v, pinned: false });
+    }
+    return out;
+}
+/** 한 줄의 고정을 뒤집는다. */
+export function togglePin(draft, key) {
+    return draft.map(d => (d.key === key ? { ...d, pinned: !d.pinned } : d));
+}
+/** 한 줄을 뺀다. */
+export function removeItem(draft, key) {
+    return draft.filter(d => d.key !== key);
+}
+/**
+ * **고정한 것은 두고 나머지만 다시 뽑는다.**
+ *
+ * 새로 받은 후보에서 **이미 고정된 것과 겹치는 것은 뺀다** — 안 그러면 같은 낱말이
+ * 두 줄이 되고, 그중 하나만 고정된 이상한 상태가 된다.
+ *
+ * 자리 수는 원래 만큼 채우되, 후보가 모자라면 **모자란 대로 둔다.** 억지로 채우려고
+ * 고정한 것을 밀어내면 사람이 고른 것을 시스템이 지우는 셈이다.
+ *
+ * 길이는 아래 마지막 `map` 이 원래 초안을 훑는 것으로 이미 묶인다 — 자리 수를 세는
+ * `break` 는 **정확성이 아니라 효율**이다(후보가 수백 개일 때 다 훑지 않으려는 것).
+ * 돌연변이로 확인했다: 그 줄을 없애도 결과가 같다.
+ */
+export function regenerateUnpinned(draft, candidates, keyOf) {
+    const 고정 = draft.filter(d => d.pinned);
+    const 고정열쇠 = new Set(고정.map(d => d.key));
+    const 자리 = draft.length - 고정.length;
+    const 새것 = [];
+    const 본것 = new Set(고정열쇠);
+    for (const v of candidates) {
+        if (새것.length >= 자리)
+            break; // 정확성이 아니라 효율 — 위 주석 참고
+        const key = keyOf(v);
+        if (본것.has(key))
+            continue;
+        본것.add(key);
+        새것.push({ key, value: v, pinned: false });
+    }
+    /* **고정한 것의 자리를 지킨다.** 앞으로 몰아 두면, 다시 뽑을 때마다 사람이 보던 줄이
+       위아래로 움직여 어디를 보고 있었는지 놓친다. */
+    const 새것들 = [...새것];
+    return draft.map(d => (d.pinned ? d : 새것들.shift())).filter((d) => d !== undefined);
+}
+/** 저장할 값들 — 화면에 보이는 차례 그대로. */
+export function draftValues(draft) {
+    return draft.map(d => d.value);
+}

package/dist/packages/core/src/components/Word/phonemeSelectBlockUtils.d.ts

@@ -0,0 +1,14 @@
+/** @public 음소 선택 블록의 한 섹션(라벨). (순환 참조 방지를 위해 컴포넌트가 아닌 여기서 정의) */
+export interface PhonemeSelectBlockSection {
+    /** 상태의 열쇠 — `selected[label]` 로 고른 값을 찾는다. 화면 글자가 아니다. */
+    label: string;
+    /** 화면에 보일 이름. 없으면 label 을 그대로 쓴다(옛 부르는 자리가 안 깨지게). */
+    displayLabel?: string;
+}
+export interface SectionValue {
+    label: string;
+    value: string;
+    /** 화면에 보일 이름. 안 주면 undefined 라, 받는 쪽이 `displayLabel ?? label` 로 읽는다. */
+    displayLabel?: string;
+}
+export declare function sectionValues(selected: Record<string, string>, sections: (PhonemeSelectBlockSection | string)[]): SectionValue[];

package/dist/packages/core/src/components/Word/phonemeSelectBlockUtils.js

@@ -0,0 +1,10 @@
+// sections 순서대로 선택된 자모를 라벨-값 쌍으로 변환한다.
+// 종성만 선택된 경우에도 초성/중성을 임의로 채워 넣지 않고, 실제로 선택된 부분만 값을 갖는다
+// (예: 종성 'ㄱ'만 선택 시 초성/중성은 빈 값 — 합성 글자 '악'으로 보이는 오해를 방지).
+export function sectionValues(selected, sections) {
+    return sections.map(s => {
+        const label = typeof s === 'string' ? s : s.label;
+        const displayLabel = typeof s === 'string' ? undefined : s.displayLabel;
+        return { label, value: selected[label] ?? '', displayLabel };
+    });
+}

package/dist/packages/core/src/components/Word/useWordTableDisplaySettings.d.ts

@@ -0,0 +1,35 @@
+import type { FilterPanelSection } from '../FilterPanel';
+import type { WordTableOrientation, WordTableContentType, WordTableCutLine, PageNumberPosition } from '../WordTable';
+import type { WordSearchResultItem } from '../../types/wordSearch';
+/** 표시(비편집) 단어표의 표 설정 값 — WordTable 렌더 props에 그대로 전달한다. */
+export interface WordTableDisplaySettings {
+    orientation: WordTableOrientation;
+    contentTypes: WordTableContentType[];
+    cutLine: WordTableCutLine;
+    showOutline: boolean;
+    showDivLine: boolean;
+    /** 표 칸 수(= 페이지당 개수, 최소 1). */
+    count: number;
+}
+/** @public */
+export interface UseWordTableDisplaySettingsResult {
+    settings: WordTableDisplaySettings;
+    /** FilterPanel sections/selected/onSelect에 그대로 넘긴다. */
+    filterSections: FilterPanelSection[];
+    filterSelected: Record<string, string | string[]>;
+    handleSelect: (value: string, sectionLabel: string) => void;
+    /** 페이지 분할 결과(페이지당 개수로 나눈 항목 묶음). 항상 1개 이상. */
+    pages: WordSearchResultItem[][];
+    /** 2페이지 이상인지 — 페이지 번호 섹션 노출·표시 여부. */
+    isPaginated: boolean;
+    /** 페이지 번호 위치. */
+    pageNumberPosition: PageNumberPosition;
+}
+/**
+ * 표시 전용 단어표(편집 없음)의 '표 설정' FilterPanel 상태·섹션을 제공하는 훅.
+ * 구성·용지 방향·외곽선, 내용이 있으면 페이지당 개수, 2페이지 이상이면 페이지 번호, 항목이 2개 이상이면
+ * 절취선, 대립쌍이면 구분선 섹션을 노출한다. 기본 섹션은 공용 빌더(wordTableSettings)로 조립한다.
+ * WordTablePopup 등 표를 미리 보여주고 인쇄하는 곳에서 쓴다.
+ * @public
+ */
+export declare function useWordTableDisplaySettings(items: WordSearchResultItem[]): UseWordTableDisplaySettingsResult;

package/dist/packages/core/src/components/Word/useWordTableDisplaySettings.js

@@ -0,0 +1,82 @@
+'use client';
+import { useMemo, useState, useCallback, useEffect } from 'react';
+import { useTranslation } from 'react-i18next';
+import { chunkItems } from '../wordTableLayout';
+import { getImageResolver, checkImageExists } from '../../utils/imageConfig';
+import { buildCompositionSection, buildOrientationSection, buildBorderSection, buildCutLineSection, buildDivLineSection, buildItemsPerPageSection, buildPageNumberSection, buildTableSettingsSelected, applyTableSettingsSelect, PAGE_NUM_POSITION_VALUE, parsePageNumberPosition, } from './wordTableSettings';
+/**
+ * 표시 전용 단어표(편집 없음)의 '표 설정' FilterPanel 상태·섹션을 제공하는 훅.
+ * 구성·용지 방향·외곽선, 내용이 있으면 페이지당 개수, 2페이지 이상이면 페이지 번호, 항목이 2개 이상이면
+ * 절취선, 대립쌍이면 구분선 섹션을 노출한다. 기본 섹션은 공용 빌더(wordTableSettings)로 조립한다.
+ * WordTablePopup 등 표를 미리 보여주고 인쇄하는 곳에서 쓴다.
+ * @public
+ */
+export function useWordTableDisplaySettings(items) {
+    const { t } = useTranslation();
+    const [orientation, setOrientation] = useState('landscape');
+    const [contentTypes, setContentTypes] = useState(['이미지', '단어', '표준 발음']);
+    const [cutLine, setCutLine] = useState('표시');
+    const [showOutline, setShowOutline] = useState(true);
+    const [showDivLine, setShowDivLine] = useState(true);
+    const [itemsPerPageSetting, setItemsPerPageSetting] = useState(8);
+    const [pageNumberPosition, setPageNumberPosition] = useState('right');
+    const itemCount = items.length;
+    const hasPairs = items.some(item => item.words.length > 1);
+    const hasColloquial = items.some(item => item.words.some(w => !!w.colloquialLabel));
+    // 페이지 분할 — 페이지당 개수(기본 8, 실제 개수보다 크면 전체로 클램프)로 나눈다. 항목이 없으면 1칸짜리 빈 표.
+    const effectiveItemsPerPage = Math.min(itemsPerPageSetting, Math.max(itemCount, 1));
+    const pages = useMemo(() => chunkItems(items, effectiveItemsPerPage), [items, effectiveItemsPerPage]);
+    const isPaginated = pages.length > 1;
+    // 표 렌더의 칸 수 = 페이지당 개수(마지막 페이지가 적어도 그리드 칸 수는 통일).
+    const count = effectiveItemsPerPage;
+    // 리졸버는 존재와 무관하게 URL만 만들므로(항목만 있으면 항상 truthy) 실제 이미지 존재 여부로 판정한다.
+    // WordCell이 이미지를 그리는 기준과 동일하게 checkImageExists(HEAD/캐시)로 확인해, 이미지가 하나도
+    // 없으면 '구성'의 이미지 버튼을 비활성화한다.
+    const [hasImage, setHasImage] = useState(false);
+    /* eslint-disable react-hooks/set-state-in-effect */
+    useEffect(() => {
+        let cancelled = false;
+        if (!getImageResolver()) {
+            setHasImage(false);
+            return;
+        }
+        Promise.all(items.flatMap(item => item.words.map(w => checkImageExists(w.label, w.homonum))))
+            .then(results => { if (!cancelled)
+            setHasImage(results.some(Boolean)); });
+        return () => { cancelled = true; };
+    }, [items]);
+    /* eslint-enable react-hooks/set-state-in-effect */
+    // 기본 5개 섹션은 공용 빌더(wordTableSettings)로 조립 — WordTableBlock과 문구·항목이 어긋나지 않는다.
+    // 편집(칸 수)은 표시 전용이라 제외하고, 페이지당 개수·페이지 번호는 WordTableBlock 표시 모드와 동일하게 포함한다.
+    const filterSections = useMemo(() => [
+        buildCompositionSection(t, { hasImage, hasColloquial }),
+        buildOrientationSection(t),
+        // 내용이 있는(1개 이상) 표면 페이지당 개수를 항상 노출.
+        ...(itemCount > 0 ? [buildItemsPerPageSection(t, { hasPairs, itemCount })] : []),
+        ...(isPaginated ? [buildPageNumberSection(t)] : []),
+        buildBorderSection(t),
+        ...(count > 1 ? [buildCutLineSection(t)] : []),
+        ...(hasPairs ? [buildDivLineSection(t)] : []),
+    ], [t, hasImage, hasColloquial, itemCount, hasPairs, isPaginated, count]);
+    const filterSelected = {
+        ...buildTableSettingsSelected(t, { contentTypes, orientation, showOutline, cutLine, showDivLine }),
+        ...(itemCount > 0 ? { [t(hasPairs ? 'wordTable.filter.itemsPerPagePair' : 'wordTable.filter.itemsPerPageWord')]: `${effectiveItemsPerPage}개` } : {}),
+        ...(isPaginated ? { [t('wordTable.filter.pageNumber', '페이지 번호')]: PAGE_NUM_POSITION_VALUE[pageNumberPosition] } : {}),
+    };
+    const handleSelect = useCallback((value, sectionLabel) => {
+        // 기본 5개 설정은 공용 헬퍼가 처리 — 처리했으면 종료. 나머지(페이지당 개수·페이지 번호)만 여기서.
+        if (applyTableSettingsSelect(t, value, sectionLabel, { setContentTypes, setOrientation, setShowOutline, setCutLine, setShowDivLine }))
+            return;
+        if (sectionLabel === t('wordTable.filter.itemsPerPagePair', '페이지당 대립쌍 수') || sectionLabel === t('wordTable.filter.itemsPerPageWord', '페이지당 단어 수')) {
+            setItemsPerPageSetting(parseInt(value));
+        }
+        else if (sectionLabel === t('wordTable.filter.pageNumber', '페이지 번호')) {
+            setPageNumberPosition(parsePageNumberPosition(value));
+        }
+    }, [t]);
+    return {
+        settings: { orientation, contentTypes, cutLine, showOutline, showDivLine, count },
+        filterSections, filterSelected, handleSelect,
+        pages, isPaginated, pageNumberPosition,
+    };
+}

package/dist/packages/core/src/components/Word/useWordTablePrint.d.ts

@@ -0,0 +1,31 @@
+/** @public */
+export interface UseWordTablePrintOptions {
+    /** 인쇄/캡처할 콘텐츠 엘리먼트들을 반환 — 다중 페이지면 페이지별, 단일 표면 콘텐츠 1개. */
+    getElements: () => HTMLElement[];
+    /** 용지 픽셀 크기(WORD_TABLE_PAPER[orientation]의 width/height). */
+    paperW: number;
+    paperH: number;
+    /** PDF 저장 시 OS 기본 파일명. */
+    fileName?: string;
+    /** 새 창 열기가 팝업 차단됐을 때 호출(openNewWindow 전용). */
+    onPopupBlocked?: () => void;
+    /** 종이 맨 위에 찍을 한 줄(누구의·언제·무슨 표). 인쇄되는 것은 격자뿐이라
+     *  이것이 없으면 뽑아 둔 종이에 아무 단서도 안 남는다. */
+    header?: string;
+}
+/** @public */
+export interface UseWordTablePrintResult {
+    /** 화면 밖 iframe에서 격리 인쇄(전역 print CSS·팝업 차단 무관). */
+    print: () => void;
+    /** 새 탭에 단어표를 열어 사용자가 직접 인쇄/저장하게 한다. */
+    openNewWindow: () => void;
+    /** 단어표를 정적 HTML 파일로 다운로드한다. */
+    downloadHtml: () => void;
+}
+/**
+ * 단어표 인쇄/새창/다운로드 액션을 한 곳에서 제공하는 훅. WordTableBlock·WordTablePopup 등
+ * 단어표를 보여주는 컴포넌트가 공용으로 쓴다. 실제 문서 생성은 wordTablePrint의 순수 함수가,
+ * 이 훅은 엘리먼트 수집·용지 크기·파일명을 묶어 React 핸들러로 노출하는 역할만 한다.
+ * @public
+ */
+export declare function useWordTablePrint({ getElements, paperW, paperH, fileName, onPopupBlocked, header, }: UseWordTablePrintOptions): UseWordTablePrintResult;

package/dist/packages/core/src/components/Word/useWordTablePrint.js

@@ -0,0 +1,43 @@
+'use client';
+import { useCallback } from 'react';
+import { captureHtml, printWordTableElements, sanitizeFileName } from './wordTablePrint';
+/**
+ * 단어표 인쇄/새창/다운로드 액션을 한 곳에서 제공하는 훅. WordTableBlock·WordTablePopup 등
+ * 단어표를 보여주는 컴포넌트가 공용으로 쓴다. 실제 문서 생성은 wordTablePrint의 순수 함수가,
+ * 이 훅은 엘리먼트 수집·용지 크기·파일명을 묶어 React 핸들러로 노출하는 역할만 한다.
+ * @public
+ */
+export function useWordTablePrint({ getElements, paperW, paperH, fileName = '', onPopupBlocked, header = '', }) {
+    const print = useCallback(() => {
+        printWordTableElements(getElements(), paperW, paperH, fileName, header);
+    }, [getElements, paperW, paperH, fileName, header]);
+    const openNewWindow = useCallback(() => {
+        const elements = getElements();
+        if (elements.length === 0)
+            return;
+        const win = window.open('', '_blank');
+        if (!win) {
+            onPopupBlocked?.();
+            return;
+        }
+        win.document.write(captureHtml(elements, paperW, paperH, false, fileName, header));
+        win.document.close();
+    }, [getElements, paperW, paperH, fileName, onPopupBlocked, header]);
+    const downloadHtml = useCallback(() => {
+        const elements = getElements();
+        if (elements.length === 0)
+            return;
+        const html = captureHtml(elements, paperW, paperH, false, fileName, header);
+        const blob = new Blob([html], { type: 'text/html;charset=utf-8' });
+        const url = URL.createObjectURL(blob);
+        // fileName은 사용자가 지정한 단어표 이름 등에서 올 수 있어, 파일시스템에서 문제되는
+        // 문자(\/:*?"<>|)를 치환하지 않으면 다운로드 파일명이 깨지거나 저장이 실패할 수 있다.
+        const safeFileName = fileName ? sanitizeFileName(fileName) : fileName;
+        const a = Object.assign(document.createElement('a'), { href: url, download: `${safeFileName}.html` });
+        document.body.appendChild(a);
+        a.click();
+        document.body.removeChild(a);
+        URL.revokeObjectURL(url);
+    }, [getElements, paperW, paperH, fileName, header]);
+    return { print, openNewWindow, downloadHtml };
+}

package/dist/packages/core/src/components/Word/wordScoreStats.d.ts

@@ -0,0 +1,77 @@
+import type { ScoreMark } from './wordTableScoring';
+/**
+ * 쌓인 채점으로 **무엇이 부족하고 다음에 무엇을 할지** 읽어 낸다.
+ *
+ * 채점 한 건은 그날의 사진일 뿐이다. 치료사가 알고 싶은 것은 그다음이다 —
+ * *지난번보다 나아지고 있나*, *계속 걸리는 낱말은 무엇인가*, *다음 시간에 무엇을 볼까*.
+ * 그 셋을 여기서 센다. 화면도 통신도 없다.
+ */
+/** 저장된 채점 한 건(서버가 주는 모양 그대로 중 필요한 것만). */
+export interface ScoreRecord {
+    scoredAt: string;
+    tableName: string;
+    tableId: string | null;
+    /** 칸 번호 → 표시 */
+    marks: Record<string, ScoreMark>;
+    /** 칸 번호 → 그때 보인 낱말. 옛 기록에는 없을 수 있다 */
+    labels: Record<string, string>;
+}
+/** 낱말 하나에 대해 쌓인 성적. */
+export interface WeakItem {
+    label: string;
+    /** 이 낱말을 매긴 횟수 */
+    tried: number;
+    o: number;
+    triangle: number;
+    x: number;
+    /** 정답률(0~1). △ 는 반 점 */
+    rate: number;
+    /** 가장 최근에 이 낱말을 매긴 결과 */
+    latest: ScoreMark;
+    /** 가장 최근에 매긴 때 */
+    latestAt: string;
+}
+/**
+ * 낱말별로 모아 **약한 것부터** 늘어놓는다.
+ *
+ * 정렬은 세 겹이다. 정답률이 낮은 것이 먼저이되, **같은 정답률이면 여러 번 틀린 것을
+ * 앞에 둔다** — 한 번 틀린 것과 다섯 번 내리 틀린 것은 무게가 다르다. 그래도 같으면
+ * 이름순으로 못 박는다(그러지 않으면 새로 고칠 때마다 차례가 흔들려, 보고 있던 줄을 놓친다).
+ *
+ * **낱말이 안 남은 옛 기록은 건너뛴다.** 칸 번호로 표를 되짚으면 그 표가 그동안 바뀌었을 때
+ * 엉뚱한 낱말의 기록이 된다 — 조용히 틀리느니 빼는 편이 낫다.
+ */
+export declare function weakItems(records: readonly ScoreRecord[]): WeakItem[];
+/** 표 한 개에 대한 흐름 — 같은 표를 여러 번 돌렸을 때 나아지고 있는가. */
+export interface TableTrend {
+    tableName: string;
+    tableId: string | null;
+    /** 오래된 것부터 */
+    rates: number[];
+    times: string[];
+    /** 처음 대비 마지막의 변화. 한 번뿐이면 null */
+    delta: number | null;
+}
+/**
+ * 표별 정답률 흐름.
+ *
+ * **한 번밖에 안 한 표의 `delta` 는 `null` 이다** — 0(변화 없음)과 다르다.
+ * 0으로 두면 "제자리걸음"으로 읽혀, 아직 재 본 적 없는 것이 나쁜 소식처럼 보인다.
+ */
+export declare function tableTrends(records: readonly ScoreRecord[]): TableTrend[];
+/**
+ * 다음에 무엇을 할지.
+ *
+ * **아직 잡히지 않은 낱말**을 고른다 — 마지막에 매긴 것이 ○ 가 아닌 것들. 정답률이 낮아도
+ * 지난번에 맞혔다면 지금 급한 것이 아니고, 정답률이 높아도 방금 틀렸으면 다시 봐야 한다.
+ * "지난번에 어땠나"가 "여태 어땠나"보다 다음 시간을 정한다.
+ *
+ * `limit` 은 한 시간에 다룰 만한 양이다. 스무 개를 늘어놓으면 고르는 일이 다시 숙제가 된다.
+ *
+ * **이 저장소는 더 이상 이것으로 화면을 그리지 않는다.** 잘라 주는 편리함이 그대로
+ * '조용한 축소'가 됐기 때문이다 — 스물다섯 개가 밀려 있어도 화면에는 여덟만 뜨고,
+ * 세는 수까지 여덟로 적히면 나머지는 없는 것이 된다(실제로 그렇게 있었다). 지금은
+ * 못 잡은 것을 **전부** 표로 늘어놓고 쪽넘김을 둔다. 다음 훈련에 담을 양을 고르는
+ * 셈에는 여전히 쓸 수 있지만, **늘어놓는 데에는 쓰지 않는다.**
+ */
+export declare function nextFocus(items: readonly WeakItem[], limit?: number): WeakItem[];

package/dist/packages/core/src/components/Word/wordScoreStats.js

@@ -0,0 +1,100 @@
+/** △ 를 반 점으로 치는 셈 — 저장할 때 서버가 쓰는 규칙과 같다. */
+function 점수(o, triangle, marked) {
+    return marked === 0 ? 0 : (o + triangle * 0.5) / marked;
+}
+/**
+ * 낱말별로 모아 **약한 것부터** 늘어놓는다.
+ *
+ * 정렬은 세 겹이다. 정답률이 낮은 것이 먼저이되, **같은 정답률이면 여러 번 틀린 것을
+ * 앞에 둔다** — 한 번 틀린 것과 다섯 번 내리 틀린 것은 무게가 다르다. 그래도 같으면
+ * 이름순으로 못 박는다(그러지 않으면 새로 고칠 때마다 차례가 흔들려, 보고 있던 줄을 놓친다).
+ *
+ * **낱말이 안 남은 옛 기록은 건너뛴다.** 칸 번호로 표를 되짚으면 그 표가 그동안 바뀌었을 때
+ * 엉뚱한 낱말의 기록이 된다 — 조용히 틀리느니 빼는 편이 낫다.
+ */
+export function weakItems(records) {
+    const 모음 = new Map();
+    /* 최근 것을 알려면 시간순으로 훑어야 한다. 서버는 최신순으로 주지만 여기서 다시
+       정렬한다 — 부르는 쪽의 차례에 기대면 그쪽이 바뀔 때 조용히 어긋난다. */
+    const 시간순 = [...records].sort((a, b) => a.scoredAt.localeCompare(b.scoredAt));
+    for (const r of 시간순) {
+        for (const [cell, mark] of Object.entries(r.marks)) {
+            const label = r.labels?.[cell];
+            if (!label)
+                continue;
+            const cur = 모음.get(label) ?? { o: 0, triangle: 0, x: 0, latest: mark, latestAt: r.scoredAt };
+            if (mark === 'o')
+                cur.o++;
+            else if (mark === 'triangle')
+                cur.triangle++;
+            else if (mark === 'x')
+                cur.x++;
+            else
+                continue;
+            cur.latest = mark;
+            cur.latestAt = r.scoredAt;
+            모음.set(label, cur);
+        }
+    }
+    const out = [];
+    for (const [label, v] of 모음) {
+        const tried = v.o + v.triangle + v.x;
+        out.push({ label, tried, o: v.o, triangle: v.triangle, x: v.x, rate: 점수(v.o, v.triangle, tried), latest: v.latest, latestAt: v.latestAt });
+    }
+    out.sort((a, b) => a.rate - b.rate || b.tried - a.tried || a.label.localeCompare(b.label));
+    return out;
+}
+/**
+ * 표별 정답률 흐름.
+ *
+ * **한 번밖에 안 한 표의 `delta` 는 `null` 이다** — 0(변화 없음)과 다르다.
+ * 0으로 두면 "제자리걸음"으로 읽혀, 아직 재 본 적 없는 것이 나쁜 소식처럼 보인다.
+ */
+export function tableTrends(records) {
+    const 모음 = new Map();
+    for (const r of records) {
+        /* 표를 지워도 이름으로는 이어 볼 수 있어야 한다 — id 가 없으면 이름을 열쇠로 쓴다. */
+        const key = r.tableId ?? `name:${r.tableName}`;
+        const cur = 모음.get(key) ?? { tableName: r.tableName, tableId: r.tableId, rows: [] };
+        cur.rows.push(r);
+        모음.set(key, cur);
+    }
+    const out = [];
+    for (const v of 모음.values()) {
+        const rows = [...v.rows].sort((a, b) => a.scoredAt.localeCompare(b.scoredAt));
+        const rates = rows.map(r => {
+            const vals = Object.values(r.marks);
+            const o = vals.filter(m => m === 'o').length;
+            const tri = vals.filter(m => m === 'triangle').length;
+            return 점수(o, tri, vals.filter(m => m === 'o' || m === 'triangle' || m === 'x').length);
+        });
+        out.push({
+            tableName: v.tableName,
+            tableId: v.tableId,
+            rates,
+            times: rows.map(r => r.scoredAt),
+            delta: rates.length >= 2 ? rates[rates.length - 1] - rates[0] : null,
+        });
+    }
+    /* 최근에 한 것부터 — 오늘 무엇을 봤는지가 먼저 눈에 들어와야 한다. */
+    out.sort((a, b) => (b.times[b.times.length - 1] ?? '').localeCompare(a.times[a.times.length - 1] ?? ''));
+    return out;
+}
+/**
+ * 다음에 무엇을 할지.
+ *
+ * **아직 잡히지 않은 낱말**을 고른다 — 마지막에 매긴 것이 ○ 가 아닌 것들. 정답률이 낮아도
+ * 지난번에 맞혔다면 지금 급한 것이 아니고, 정답률이 높아도 방금 틀렸으면 다시 봐야 한다.
+ * "지난번에 어땠나"가 "여태 어땠나"보다 다음 시간을 정한다.
+ *
+ * `limit` 은 한 시간에 다룰 만한 양이다. 스무 개를 늘어놓으면 고르는 일이 다시 숙제가 된다.
+ *
+ * **이 저장소는 더 이상 이것으로 화면을 그리지 않는다.** 잘라 주는 편리함이 그대로
+ * '조용한 축소'가 됐기 때문이다 — 스물다섯 개가 밀려 있어도 화면에는 여덟만 뜨고,
+ * 세는 수까지 여덟로 적히면 나머지는 없는 것이 된다(실제로 그렇게 있었다). 지금은
+ * 못 잡은 것을 **전부** 표로 늘어놓고 쪽넘김을 둔다. 다음 훈련에 담을 양을 고르는
+ * 셈에는 여전히 쓸 수 있지만, **늘어놓는 데에는 쓰지 않는다.**
+ */
+export function nextFocus(items, limit = 8) {
+    return items.filter(i => i.latest !== 'o').slice(0, limit);
+}

package/dist/packages/core/src/components/Word/wordTableBlockTypes.d.ts

@@ -0,0 +1,85 @@
+/**
+ * wordTableBlockTypes.ts
+ * WordTableBlock의 순수 타입 및 인터페이스 정의.
+ */
+import type { ReactNode } from 'react';
+import type { WordSearchResultItem } from './WordSearchResultBlock';
+export interface WordEntry {
+    word: string;
+    pronunciation: string;
+    grade?: string;
+    pos?: string;
+    wordType?: string;
+    field?: string;
+    homonum?: number;
+    colloquialPronunciation?: string;
+}
+/** @public */
+export interface WordTableBlockProps {
+    title?: ReactNode;
+    titleIcon?: string;
+    disc?: ReactNode;
+    /** 현재 표의 저장된 이름(불러온 표 등). 있으면 인쇄/PDF 저장 시 파일명으로 사용, 없으면 "오늘 날짜 + 단어표/대립쌍표" */
+    tableName?: string;
+    /** 전달하면 외부 데이터 표시 모드, 없으면 편집 모드 */
+    items?: WordSearchResultItem[];
+    /** 전달하면 저장 팝업을 내부에서 열고 확인 후 name·items·description을 전달.
+     *  saveAsNew=true면 '다른 이름으로 저장'(수정 대신 새 표 생성)을 뜻한다. */
+    onSaveComplete?: (name: string, items: WordSearchResultItem[], description?: string, saveAsNew?: boolean) => void;
+    onLoad?: () => void;
+    onRemoveItem?: (id: string) => void;
+    /** 전달하면 액션 영역 왼쪽에 초기화 버튼 표시 */
+    onReset?: () => void;
+    resetLabel?: string;
+    /** 저장 버튼 라벨 override — 미지정 시 '저장하기'(수정 모드에서 '수정하기' 등으로 교체) */
+    saveButtonLabel?: string;
+    /** 지정하면 저장 버튼 왼쪽에 '다른 이름으로 저장'(새 표 생성) 보조 버튼을 표시한다. 수정 모드용. */
+    secondarySaveButtonLabel?: string;
+    /** 지정하면(onNameChange 존재) 표 구성 화면에 이름·설명 입력란을 표시하고, 저장은 팝업 없이 즉시 처리한다. */
+    nameValue?: string;
+    onNameChange?: (value: string) => void;
+    descriptionValue?: string;
+    onDescriptionChange?: (value: string) => void;
+    /** 이름·설명 자동 제안 — placeholder로 실시간 표시하고, 입력이 비어 있으면 저장 시 이 값을 사용한다. */
+    namePlaceholder?: string;
+    descriptionPlaceholder?: string;
+    /** 인라인 이름 중복 검사용 — 전체 표 이름 목록. */
+    existingNames?: string[];
+    /** 수정 중인 표의 저장된 이름 — '저장하기'(덮어쓰기)에서 자기 이름과의 충돌은 허용하기 위해 검사에서 제외. */
+    editingName?: string;
+    /** 지정하면 인쇄하기 왼쪽에 '취소' 버튼을 표시(PagePopup 닫기 등). */
+    onCancel?: () => void;
+    /** 전달하면 카드 드래그로 순서 변경 가능 */
+    onReorder?: (fromIndex: number, toIndex: number) => void;
+    /** display 모드에서도 칸 수 조절 허용 */
+    showCellCount?: boolean;
+    /** display 모드에서 빈 슬롯에 추가하기 버튼 표시 */
+    onAddItem?: (item: WordSearchResultItem) => void;
+    className?: string;
+    /** 저장 팝업 렌더러 */
+    renderSavePopup?: (props: {
+        defaultName?: string;
+        preview?: ReactNode;
+        previewW?: number;
+        previewH?: number;
+        items?: WordSearchResultItem[];
+        existingNames?: string[];
+        /** '다른 이름으로 저장'으로 팝업이 열렸는지 — 렌더러가 기본 이름/제목을 다르게 줄 수 있다. */
+        saveAsNew?: boolean;
+        onSave: (name: string, description?: string) => void;
+        onCancel: () => void;
+    }) => ReactNode;
+    /** 단어 검색 팝업 렌더러 */
+    renderWordSearch?: (props: {
+        cellIndex: number;
+        onConfirm: (words: WordEntry[]) => void;
+        onClose: () => void;
+    }) => ReactNode;
+    /** true 이면 FilterPanel·액션 버튼 숨김, WordTable만 표시 */
+    hideControls?: boolean;
+    /** 액션 중 저장 버튼만 노출 (불러오기/새 창/인쇄 숨김) */
+    saveOnly?: boolean;
+}
+export declare const CELL_COUNTS: number[];
+/** 표시(인쇄) 모드에서 선택 가능한 "페이지당 개수"(단어/대립쌍 수) — 이 값 그대로 페이지당 칸 수가 된다 */
+export declare const ITEMS_PER_PAGE_OPTIONS: number[];

package/dist/packages/core/src/components/Word/wordTableBlockTypes.js

@@ -0,0 +1,3 @@
+export const CELL_COUNTS = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12];
+/** 표시(인쇄) 모드에서 선택 가능한 "페이지당 개수"(단어/대립쌍 수) — 이 값 그대로 페이지당 칸 수가 된다 */
+export const ITEMS_PER_PAGE_OPTIONS = [8, 4, 2, 1];

package/dist/packages/core/src/components/Word/wordTablePrint.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 파일명(문서 title·다운로드 파일명)에 쓰이는 사용자 입력값(단어표 이름 등)에서 Windows/macOS
+ * 파일시스템에서 문제되는 문자(\ / : * ? " < > |)를 밑줄로 치환한다. 없으면 "PDF로 저장"·
+ * .html 다운로드 시 파일명이 깨지거나 저장 자체가 실패할 수 있다.
+ */
+export declare function sanitizeFileName(name: string): string;
+/**
+ * 캡처한 콘텐츠 엘리먼트들을 화면 밖 숨김 iframe에서 인쇄한다. 전역 @media print(모든
+ * .word-table 노출)나 팝업 차단의 간섭 없이 넘긴 엘리먼트만 격리 인쇄한다. WordTableBlock의
+ * 다중 페이지 인쇄와 WordTablePopup의 단일 표 인쇄가 공용으로 쓴다.
+ * @public
+ */
+export declare function printWordTableElements(elements: HTMLElement[], paperW: number, paperH: number, fileName?: string, header?: string): void;
+export declare function captureHtml(els: HTMLElement[], paperW: number, paperH: number, autoPrint?: boolean, fileName?: string, header?: string): string;