@ihabdevteam/core 0.441.0 → 0.443.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/CHANGELOG.md +21 -0
  2. package/dist/components.cjs.js +190 -190
  3. package/dist/components.esm.css +2 -2
  4. package/dist/hooks.cjs.js +5 -5
  5. package/dist/i18n.cjs.js +1 -1
  6. package/dist/ihabdevteam-core.cjs.js +186 -186
  7. package/dist/ihabdevteam-core.d.ts +296 -1
  8. package/dist/packages/core/src/components/ErrorBoundary.d.ts +55 -0
  9. package/dist/packages/core/src/components/ErrorBoundary.js +52 -0
  10. package/dist/packages/core/src/components/KeepScreenAwake.d.ts +9 -0
  11. package/dist/packages/core/src/components/KeepScreenAwake.js +12 -0
  12. package/dist/packages/core/src/components/MarkIcon.css +12 -0
  13. package/dist/packages/core/src/components/MarkIcon.d.ts +20 -0
  14. package/dist/packages/core/src/components/MarkIcon.js +18 -0
  15. package/dist/packages/core/src/components/PagePopup.d.ts +43 -0
  16. package/dist/packages/core/src/components/PagePopup.js +71 -0
  17. package/dist/packages/core/src/components/Popup/ListPopup.js +3 -1
  18. package/dist/packages/core/src/components/Popup/Popup.js +2 -1
  19. package/dist/packages/core/src/components/Popup/useDiscardGuard.d.ts +26 -0
  20. package/dist/packages/core/src/components/Popup/useDiscardGuard.js +28 -0
  21. package/dist/packages/core/src/components/ScoreMarkCounts.css +9 -0
  22. package/dist/packages/core/src/components/ScoreMarkCounts.d.ts +19 -0
  23. package/dist/packages/core/src/components/ScoreMarkCounts.js +16 -0
  24. package/dist/packages/core/src/components.d.ts +12 -2
  25. package/dist/packages/core/src/components.js +8 -1
  26. package/dist/packages/core/src/hooks/useClosingDelay.d.ts +12 -0
  27. package/dist/packages/core/src/hooks/useClosingDelay.js +30 -0
  28. package/dist/packages/core/src/hooks/useOnline.d.ts +9 -0
  29. package/dist/packages/core/src/hooks/useOnline.js +23 -0
  30. package/dist/packages/core/src/hooks/useOutsideClose.d.ts +11 -0
  31. package/dist/packages/core/src/hooks/useOutsideClose.js +23 -0
  32. package/dist/packages/core/src/hooks/usePageSizeOptions.d.ts +19 -0
  33. package/dist/packages/core/src/hooks/usePageSizeOptions.js +25 -0
  34. package/dist/packages/core/src/hooks/useSaveOnHide.d.ts +14 -0
  35. package/dist/packages/core/src/hooks/useSaveOnHide.js +32 -0
  36. package/dist/packages/core/src/hooks/useScreenWakeLock.d.ts +12 -0
  37. package/dist/packages/core/src/hooks/useScreenWakeLock.js +53 -0
  38. package/dist/packages/core/src/hooks.d.ts +6 -0
  39. package/dist/packages/core/src/hooks.js +7 -0
  40. package/dist/packages/core/src/utils/kstDateTime.d.ts +21 -0
  41. package/dist/packages/core/src/utils/kstDateTime.js +38 -0
  42. package/dist/packages/core/src/utils/popupTiming.d.ts +7 -0
  43. package/dist/packages/core/src/utils/popupTiming.js +7 -0
  44. package/dist/packages/core/src/utils.d.ts +2 -0
  45. package/dist/packages/core/src/utils.js +1 -0
  46. package/dist/packages/core/src/version.d.ts +1 -1
  47. package/dist/packages/core/src/version.js +1 -1
  48. package/dist/utils.cjs.js +166 -166
  49. package/package.json +1 -1
@@ -0,0 +1,71 @@
1
+ 'use client';
2
+ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
3
+ import { useCallback, useEffect, useRef, useState } from 'react';
4
+ import { cx } from '../utils/cx';
5
+ import { useFocusTrap, FOCUSABLE_SELECTOR } from '../hooks/useFocusTrap';
6
+ import { lockBodyScrollWithPadding } from '../hooks/bodyScrollLock';
7
+ import { prefersReducedMotion } from '../hooks/usePrefersReducedMotion';
8
+ import { PAGE_POPUP_CLOSE_MS } from './Training/pagePopupTiming';
9
+ import './Training/TrainingPagePopup.css';
10
+ /**
11
+ * **훈련이 아닌 전체 화면 창의 껍데기**(말귀 청 (437) ㉰ — 말귀 앱에서 옮겨 왔다, 2026-11-13).
12
+ *
13
+ * 생김새는 `TrainingPagePopup` 과 같은 `page-popup` 이고, 걸음 넘기기 · 소음 · 결과는 없다 — 단어표 채점 창처럼 화면을 덮는
14
+ * 아무 창이나 담는다. 자리 셋(`top` · 본문 · `bottom`)만 쥐고 내용은 부르는 쪽이 넣는다. 닫힘은 `usePagePopupClose` 와 짝이다.
15
+ *
16
+ * · **열 때 판 안으로 초점을 옮기고, 닫힐 때 부른 자리로 되돌린다.** 부른 자리는 효과가 아니라 **그리는 중**에 적는다 —
17
+ * 자식의 `autoFocus` 는 커밋 중에 걸려, 효과에서 읽으면 부른 사람이 아니라 그 자식이 적힌다.
18
+ * · Tab 은 판 안을 돈다(`useFocusTrap`).
19
+ * @public
20
+ */
21
+ export default function PagePopup({ children, top, bottom, mode = 'top', contentFull = false, closing = false, className, 'aria-label': ariaLabel }) {
22
+ const panelRef = useRef(null);
23
+ const previouslyFocusedRef = useRef(typeof document === 'undefined' ? null : document.activeElement);
24
+ useEffect(() => {
25
+ const previouslyFocused = previouslyFocusedRef.current;
26
+ const panel = panelRef.current;
27
+ if (panel && !panel.contains(document.activeElement)) {
28
+ const first = panel.querySelector(FOCUSABLE_SELECTOR);
29
+ (first ?? panel).focus();
30
+ }
31
+ return () => { previouslyFocused?.focus?.(); };
32
+ }, []);
33
+ useFocusTrap(panelRef);
34
+ return (_jsx("div", { className: cx('page-popup', closing && 'page-popup--closing', className), role: "dialog", "aria-modal": "true", "aria-label": ariaLabel, children: _jsxs("div", { className: "page-popup__panel", ref: panelRef, tabIndex: -1, children: [top && _jsx("div", { className: "page-popup__top", children: top }), _jsx("div", { className: "page-popup__scroll", children: _jsx("div", { className: cx('page-popup__content', mode === 'center' ? 'page-popup__content--center' : 'page-popup__content--top', contentFull && 'page-popup__content--full'), children: children }) }), bottom && _jsx("div", { className: "page-popup__bottom", children: bottom })] }) }));
35
+ }
36
+ /**
37
+ * **전체 화면 창이 사라지는 동안의 뒷일** — `PagePopup` 의 짝(말귀 청 (437) ㉰).
38
+ *
39
+ * · **한 번만 닫힌다** — ESC · 닫기 단추 · 안쪽 '완료' 가 잇달아 들어와도 첫 번째만 먹는다(타이머가 여럿 걸려 `onClose` 가 두 번 불리지 않게).
40
+ * · **다 사라진 뒤에 떼어 낸다** — `closing` 을 켜고 `PAGE_POPUP_CLOSE_MS` 기다렸다가 `onClose`. **움직임 줄이기면 0** 이다.
41
+ * · **`onClose` 가 던지면 풀린다** — 안 풀면 닫기 가드가 걸린 채 남아 다시는 못 닫는다(`TrainingPagePopup` 과 같은 고침 — 앱 사본엔 둘 다 없었다).
42
+ * · 떠 있는 동안 뒤 화면 스크롤을 잠근다. 화면을 떠나면 타이머를 끈다.
43
+ * @public
44
+ */
45
+ export function usePagePopupClose(onClose) {
46
+ const [closing, setClosing] = useState(false);
47
+ const closingRef = useRef(false);
48
+ const timerRef = useRef(null);
49
+ const handleClose = useCallback(() => {
50
+ if (closingRef.current)
51
+ return;
52
+ closingRef.current = true;
53
+ setClosing(true);
54
+ timerRef.current = setTimeout(() => {
55
+ timerRef.current = null;
56
+ /* 던지면 가드를 풀고 남긴다 — `TrainingPagePopup` 의 scheduleClose 와 같다(다시 던지면 타이머 밖이라 아무도 못 잡는다) */
57
+ try {
58
+ onClose();
59
+ }
60
+ catch (e) {
61
+ closingRef.current = false;
62
+ setClosing(false);
63
+ console.error(e);
64
+ }
65
+ }, prefersReducedMotion() ? 0 : PAGE_POPUP_CLOSE_MS);
66
+ }, [onClose]);
67
+ useEffect(() => lockBodyScrollWithPadding(), []);
68
+ useEffect(() => () => { if (timerRef.current)
69
+ clearTimeout(timerRef.current); }, []);
70
+ return { closing, handleClose };
71
+ }
@@ -8,6 +8,7 @@ import Toolbar from '../Toolbar';
8
8
  import './ListPopup.css';
9
9
  import { compareCellBlankLast } from '../../utils/textSort';
10
10
  import { cx } from '../../utils/cx';
11
+ import { usePageSizeOptions } from '../../hooks/usePageSizeOptions';
11
12
  /** @public */
12
13
  export default function ListPopup(props) {
13
14
  const { title, items, columns, resizeStorageKey, gridTemplateColumns, mobileGridTemplateColumns, searchPlaceholder, searchFn, defaultSortKey, defaultSortAsc = true, selectedId, selectedIds, onSelect, onClose, pageSizeOptions = [10, 25, 50, 100], initialPageSize, emptyText, noMatchText, countLabel, topContent, className = '', } = props;
@@ -98,7 +99,8 @@ export default function ListPopup(props) {
98
99
  className: col.className,
99
100
  sortDir: col.sortable !== false && sortKey === col.key ? (sortAsc ? 'asc' : 'desc') : null,
100
101
  })), [columns, sortKey, sortAsc, handleSort]);
101
- const pageSizeOpts = useMemo(() => pageSizeOptions.map(n => ({ value: String(n), label: t('common.pageSizeLabel', { n }) })), [pageSizeOptions, t]);
102
+ /* "N개씩 보기" 목록은 공용 훅 한 벌(청 (437) ㉳ⓐ) — 전엔 여기서 같은 것을 지었다 */
103
+ const pageSizeOpts = usePageSizeOptions(pageSizeOptions);
102
104
  return (_jsxs(Popup, { className: `popup-list ${className}`, title: title, onClose: onClose, children: [topContent, 'label' in countParts && _jsx("p", { className: "toolbar__count body-1", children: countParts.label }), _jsx(Toolbar, { count: 'label' in countParts ? undefined : { value: filtered.length, prefix: countParts.prefix, suffix: countParts.suffix }, search: searchEnabled ? { value: search, onChange: setSearch, placeholder: resolvedSearchPlaceholder } : undefined, pageSize: { options: pageSizeOpts, value: pageSize, onChange: setPageSize }, pagination: { page: clampedPage, total: totalPages, onChange: setPage } }), _jsx(Table, { gridTemplateColumns: gridTemplateColumns, mobileGridTemplateColumns: mobileGridTemplateColumns,
103
105
  /* 폭 조절은 켜고, 저장 열쇠는 **부르는 쪽이 고른다**((306), 2026-10-14).
104
106
 
@@ -11,7 +11,8 @@ import "./Popup.css";
11
11
  import { useFocusTrap, FOCUSABLE_SELECTOR } from '../../hooks/useFocusTrap';
12
12
  import { rememberFocusReturn, resolveFocusReturn } from '../../hooks/focusReturn';
13
13
  import { usePrefersReducedMotion } from '../../hooks/usePrefersReducedMotion';
14
- const ANIM_MS = 260;
14
+ import { POPUP_CLOSE_MS } from '../../utils/popupTiming';
15
+ const ANIM_MS = POPUP_CLOSE_MS; // 닫힘 시간은 한 곳(popupTiming.ts) — 앱도 그 수를 받아 쓴다(청 (437) ㉳ⓑ)
15
16
  // 패널 안에서 Tab 순환 대상으로 삼을 요소들 — disabled/tabindex="-1"은 제외.
16
17
  /** @public */
17
18
  export default function Popup(props) {
@@ -46,3 +46,29 @@ export interface DiscardGuard {
46
46
  * @public
47
47
  */
48
48
  export declare function useDiscardGuard(isDirty: boolean, onClose: () => void, labels?: DiscardGuardLabels): DiscardGuard;
49
+ /** @public `useValueDiscardGuard` 가 돌려주는 것 — `DiscardGuard` 에 지금 달라졌나 · 기준 다시 잡기를 더한 것 */
50
+ export interface ValueDiscardGuard extends DiscardGuard {
51
+ /** 첫 값과 지금 값이 다른가 — 저장 단추를 켜고 끌 때도 쓴다 */
52
+ isDirty: boolean;
53
+ /** **지금 값을 새 기준으로 잡는다** — 늦게 불러온 값을 채운 뒤나, 저장해 놓고 창을 안 닫고 이어 쓸 때 부른다 */
54
+ rebase: () => void;
55
+ }
56
+ /**
57
+ * **값으로 묻는 닫기 막이** — 창이 처음 열린 때의 값과 지금 값을 견줘, 달라졌으면 닫기 전에 묻는다
58
+ * (말귀 청 (437) ㉯, 2026-11-13).
59
+ *
60
+ * `useDiscardGuard` 는 참 · 거짓만 받는다. 그래서 말귀 앱 여섯 창이 저마다
61
+ * `const [first] = useState(() => JSON.stringify(x))` 로 첫 모습을 얼리고 `JSON.stringify(cur) !== first` 를 넘겼다
62
+ * (회사 정보 · 정보 입력 · 방문 고치기 · 방문 등록 · 고객 추가 · 단어훈련 묶음). 그 두 줄을 여기 한 벌로 둔다.
63
+ *
64
+ * · 첫 값은 **처음 그릴 때 한 번** 얼린다 — 그 뒤 부르는 쪽이 새 객체를 넘겨도 기준은 안 바뀐다.
65
+ * · 견주기는 JSON 꼴로 한다 — 자리만 같고 새로 만든 객체 · 배열이어도 내용이 같으면 '안 달라짐' 이다.
66
+ * (그래서 값에는 JSON 으로 옮길 수 있는 것만 넣는다 — 함수 · `Date` 의 시각 차 · `undefined` 칸은 견주기에서 빠진다.)
67
+ * · 값을 늦게 불러오는 창은 다 불러온 뒤 `rebase()` 를 부른다 — 안 부르면 빈 첫 값과 견줘 늘 '달라짐' 이 된다.
68
+ *
69
+ * ```tsx
70
+ * const { beforeClose, discardPopup, allowClose, isDirty } = useValueDiscardGuard(form, onClose)
71
+ * ```
72
+ * @public
73
+ */
74
+ export declare function useValueDiscardGuard(value: unknown, onClose: () => void, labels?: DiscardGuardLabels): ValueDiscardGuard;
@@ -54,3 +54,31 @@ export function useDiscardGuard(isDirty, onClose, labels = {}) {
54
54
  const discardPopup = confirming ? (_jsx(ConfirmPopup, { title: labels.title ?? t('common.discardConfirm.title', '입력을 취소할까요?'), message: labels.message ?? t('common.discardConfirm.body', '저장하지 않으면 지금까지 입력한 내용이 사라집니다.'), confirmLabel: labels.confirmLabel ?? t('common.discardConfirm.confirm', '입력 취소'), confirmVariant: "danger", onConfirm: () => { setConfirming(false); onClose(); }, onClose: () => setConfirming(false) })) : null;
55
55
  return { beforeClose, discardPopup, allowClose };
56
56
  }
57
+ /**
58
+ * **값으로 묻는 닫기 막이** — 창이 처음 열린 때의 값과 지금 값을 견줘, 달라졌으면 닫기 전에 묻는다
59
+ * (말귀 청 (437) ㉯, 2026-11-13).
60
+ *
61
+ * `useDiscardGuard` 는 참 · 거짓만 받는다. 그래서 말귀 앱 여섯 창이 저마다
62
+ * `const [first] = useState(() => JSON.stringify(x))` 로 첫 모습을 얼리고 `JSON.stringify(cur) !== first` 를 넘겼다
63
+ * (회사 정보 · 정보 입력 · 방문 고치기 · 방문 등록 · 고객 추가 · 단어훈련 묶음). 그 두 줄을 여기 한 벌로 둔다.
64
+ *
65
+ * · 첫 값은 **처음 그릴 때 한 번** 얼린다 — 그 뒤 부르는 쪽이 새 객체를 넘겨도 기준은 안 바뀐다.
66
+ * · 견주기는 JSON 꼴로 한다 — 자리만 같고 새로 만든 객체 · 배열이어도 내용이 같으면 '안 달라짐' 이다.
67
+ * (그래서 값에는 JSON 으로 옮길 수 있는 것만 넣는다 — 함수 · `Date` 의 시각 차 · `undefined` 칸은 견주기에서 빠진다.)
68
+ * · 값을 늦게 불러오는 창은 다 불러온 뒤 `rebase()` 를 부른다 — 안 부르면 빈 첫 값과 견줘 늘 '달라짐' 이 된다.
69
+ *
70
+ * ```tsx
71
+ * const { beforeClose, discardPopup, allowClose, isDirty } = useValueDiscardGuard(form, onClose)
72
+ * ```
73
+ * @public
74
+ */
75
+ export function useValueDiscardGuard(value, onClose, labels = {}) {
76
+ const now = JSON.stringify(value);
77
+ const [first, setFirst] = useState(now);
78
+ const isDirty = now !== first;
79
+ const guard = useDiscardGuard(isDirty, onClose, labels);
80
+ const nowRef = useRef(now);
81
+ nowRef.current = now;
82
+ const rebase = useCallback(() => setFirst(nowRef.current), []);
83
+ return { ...guard, isDirty, rebase };
84
+ }
@@ -0,0 +1,9 @@
1
+ /* 매긴 셈 한 묶음(말귀 청 (437) ㉱) — 셋을 한 묶음으로, 사이를 넓히면 저마다 떠서 '셋 중 하나' 로 안 읽힌다 */
2
+ .score-mark-counts { display: flex; align-items: center; gap: 12px; }
3
+ .score-mark-counts__one { display: flex; align-items: center; gap: 5px; }
4
+ .score-mark-counts__num {
5
+ font-size: 15px;
6
+ font-weight: 600;
7
+ color: var(--color-black);
8
+ font-variant-numeric: tabular-nums;
9
+ }
@@ -0,0 +1,19 @@
1
+ import type { ScoreMark } from './Word/wordTableScoring';
2
+ import './ScoreMarkCounts.css';
3
+ /** @public */
4
+ export interface ScoreMarkCountsProps {
5
+ o: number;
6
+ triangle: number;
7
+ x: number;
8
+ /** 낭독기에 읽힐 이름 — **곁에 셈을 읽는 줄이 없을 때만** 준다. 안 주면 셋 다 그림으로만 선다 */
9
+ label?: (mark: ScoreMark, count: number) => string;
10
+ className?: string;
11
+ }
12
+ /**
13
+ * **매긴 셈 한 묶음 — ○ n · △ n · ✕ n**(말귀 청 (437) ㉱ — 말귀 앱에서 옮겨 왔다, 2026-11-13).
14
+ *
15
+ * · **셋을 늘 함께 세운다. 0 도 세운다** — 빠지면 `○ 2 · ✕ 1` 이 되어 △ 를 안 매긴 것인지 △ 가 없는 표인지 가릴 수 없다.
16
+ * · **들리는 말은 여기서 안 낸다** — 쓰는 자리마다 곁에 `role="status"` 한 줄이 셈을 통째로 읽는다. 곁에 그런 줄이 없으면 `label` 을 준다.
17
+ * @public
18
+ */
19
+ export default function ScoreMarkCounts({ o, triangle, x, label, className }: ScoreMarkCountsProps): import("react").JSX.Element;
@@ -0,0 +1,16 @@
1
+ 'use client';
2
+ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
3
+ import { cx } from '../utils/cx';
4
+ import MarkIcon from './MarkIcon';
5
+ import './ScoreMarkCounts.css';
6
+ /**
7
+ * **매긴 셈 한 묶음 — ○ n · △ n · ✕ n**(말귀 청 (437) ㉱ — 말귀 앱에서 옮겨 왔다, 2026-11-13).
8
+ *
9
+ * · **셋을 늘 함께 세운다. 0 도 세운다** — 빠지면 `○ 2 · ✕ 1` 이 되어 △ 를 안 매긴 것인지 △ 가 없는 표인지 가릴 수 없다.
10
+ * · **들리는 말은 여기서 안 낸다** — 쓰는 자리마다 곁에 `role="status"` 한 줄이 셈을 통째로 읽는다. 곁에 그런 줄이 없으면 `label` 을 준다.
11
+ * @public
12
+ */
13
+ export default function ScoreMarkCounts({ o, triangle, x, label, className }) {
14
+ const three = [['o', o], ['triangle', triangle], ['x', x]];
15
+ return (_jsx("span", { className: cx('score-mark-counts', className), children: three.map(([mark, count]) => (_jsxs("span", { className: "score-mark-counts__one", children: [_jsx(MarkIcon, { mark: mark, label: label ? label(mark, count) : '' }), _jsx("span", { className: "score-mark-counts__num", children: count })] }, mark))) }));
16
+ }
@@ -111,6 +111,16 @@ export { default as CardSection } from './components/CardSection';
111
111
  export type { CardSectionProps } from './components/CardSection';
112
112
  export { default as FolderSearchSections } from './components/FolderSearchSections';
113
113
  export type { FolderSearchSectionsProps } from './components/FolderSearchSections';
114
+ export { default as PagePopup, usePagePopupClose } from './components/PagePopup';
115
+ export type { PagePopupProps } from './components/PagePopup';
116
+ export { default as MarkIcon } from './components/MarkIcon';
117
+ export type { MarkIconProps } from './components/MarkIcon';
118
+ export { default as ScoreMarkCounts } from './components/ScoreMarkCounts';
119
+ export type { ScoreMarkCountsProps } from './components/ScoreMarkCounts';
120
+ export { default as KeepScreenAwake } from './components/KeepScreenAwake';
121
+ export { default as ErrorBoundary } from './components/ErrorBoundary';
122
+ export type { ErrorBoundaryProps, ErrorFallbackProps } from './components/ErrorBoundary';
123
+ export { POPUP_CLOSE_MS } from './utils/popupTiming';
114
124
  export { default as FolderTreeButton } from './components/FolderTreeButton';
115
125
  export type { FolderTreeButtonProps } from './components/FolderTreeButton';
116
126
  export { default as FolderTreeTooltip } from './components/Tooltip/FolderTreeTooltip';
@@ -269,8 +279,8 @@ export { default as ListPopup } from './components/Popup/ListPopup';
269
279
  export type { PopupListProps, PopupListColumn } from './components/Popup/ListPopup';
270
280
  export { default as ConfirmPopup } from './components/Popup/ConfirmPopup';
271
281
  export type { ConfirmPopupProps } from './components/Popup/ConfirmPopup';
272
- export { useDiscardGuard } from './components/Popup/useDiscardGuard';
273
- export type { DiscardGuard, DiscardGuardLabels } from './components/Popup/useDiscardGuard';
282
+ export { useDiscardGuard, useValueDiscardGuard } from './components/Popup/useDiscardGuard';
283
+ export type { DiscardGuard, DiscardGuardLabels, ValueDiscardGuard } from './components/Popup/useDiscardGuard';
274
284
  export { default as CouponInputPopup } from './components/Popup/CouponInputPopup';
275
285
  export type { CouponInputPopupProps } from './components/Popup/CouponInputPopup';
276
286
  export { default as MenuTooltip } from './components/Tooltip/MenuTooltip';
@@ -77,6 +77,13 @@ export { default as FolderGrid } from './components/FolderGrid';
77
77
  /* 폴더 화면의 남은 조각(말귀 청 (437) ㉮, 2026-11-13) — 카드가 서는 자리 · 찾는 중 폴더마다 나눠 세우기 */
78
78
  export { default as CardSection } from './components/CardSection';
79
79
  export { default as FolderSearchSections } from './components/FolderSearchSections';
80
+ /* 말귀 앱에서 옮겨 온 조각(청 (437) ㉰ ㉱ ㉲ ㉳ⓑ ㉴, 2026-11-13) */
81
+ export { default as PagePopup, usePagePopupClose } from './components/PagePopup';
82
+ export { default as MarkIcon } from './components/MarkIcon';
83
+ export { default as ScoreMarkCounts } from './components/ScoreMarkCounts';
84
+ export { default as KeepScreenAwake } from './components/KeepScreenAwake';
85
+ export { default as ErrorBoundary } from './components/ErrorBoundary';
86
+ export { POPUP_CLOSE_MS } from './utils/popupTiming';
80
87
  export { default as FolderTreeButton } from './components/FolderTreeButton';
81
88
  export { default as FolderTreeTooltip } from './components/Tooltip/FolderTreeTooltip';
82
89
  export { default as Rating } from './components/Rating';
@@ -196,7 +203,7 @@ export { default as TableFilterPanel } from './components/Word/TableFilterPanel'
196
203
  export { default as ContrastFilterPanel } from './components/Word/ContrastFilterPanel';
197
204
  export { default as ListPopup } from './components/Popup/ListPopup';
198
205
  export { default as ConfirmPopup } from './components/Popup/ConfirmPopup';
199
- export { useDiscardGuard } from './components/Popup/useDiscardGuard';
206
+ export { useDiscardGuard, useValueDiscardGuard } from './components/Popup/useDiscardGuard';
200
207
  export { default as CouponInputPopup } from './components/Popup/CouponInputPopup';
201
208
  export { default as MenuTooltip } from './components/Tooltip/MenuTooltip';
202
209
  export { default as InfoTooltip } from './components/Tooltip/InfoTooltip';
@@ -0,0 +1,12 @@
1
+ /**
2
+ * **창이 사라질 짬을 준 뒤에 치른다**(말귀 청 (437) ㉳ⓑ — 말귀 앱에서 옮겨 왔다, 2026-11-13).
3
+ *
4
+ * 고객을 지우는 것처럼 **이 창 자체가 없어지는** 일은, 곧바로 치르면 창이 붙은 채로 바깥이 목록을 다시 그려 사라지는 그림과
5
+ * 겹친다. 한 박자 늦추면 창이 먼저 가고 목록이 그다음이다. 기다리는 시간은 `Popup` 의 닫힘 시간(`POPUP_CLOSE_MS`) — 움직임
6
+ * 줄이기에서는 `Popup` 처럼 0 이다(앱 사본은 260 을 베껴 들고 움직임 줄이기를 몰랐다).
7
+ *
8
+ * · **기다리는 동안 창이 먼저 없어질 수 있다** — 걷힐 때 반드시 시계를 끈다(없는 창이 남긴 일이 뒤늦게 터지지 않게).
9
+ * · 한 번에 **하나만** 잰다 — 다시 부르면 앞의 것을 덮어쓴다. 두 번 눌러도 일은 한 번만 난다.
10
+ * @public
11
+ */
12
+ export declare function useClosingDelay(waitMs?: number): (todo?: () => void) => void;
@@ -0,0 +1,30 @@
1
+ 'use client';
2
+ import { useCallback, useEffect, useRef } from 'react';
3
+ import { POPUP_CLOSE_MS } from '../utils/popupTiming';
4
+ import { prefersReducedMotion } from './usePrefersReducedMotion';
5
+ /**
6
+ * **창이 사라질 짬을 준 뒤에 치른다**(말귀 청 (437) ㉳ⓑ — 말귀 앱에서 옮겨 왔다, 2026-11-13).
7
+ *
8
+ * 고객을 지우는 것처럼 **이 창 자체가 없어지는** 일은, 곧바로 치르면 창이 붙은 채로 바깥이 목록을 다시 그려 사라지는 그림과
9
+ * 겹친다. 한 박자 늦추면 창이 먼저 가고 목록이 그다음이다. 기다리는 시간은 `Popup` 의 닫힘 시간(`POPUP_CLOSE_MS`) — 움직임
10
+ * 줄이기에서는 `Popup` 처럼 0 이다(앱 사본은 260 을 베껴 들고 움직임 줄이기를 몰랐다).
11
+ *
12
+ * · **기다리는 동안 창이 먼저 없어질 수 있다** — 걷힐 때 반드시 시계를 끈다(없는 창이 남긴 일이 뒤늦게 터지지 않게).
13
+ * · 한 번에 **하나만** 잰다 — 다시 부르면 앞의 것을 덮어쓴다. 두 번 눌러도 일은 한 번만 난다.
14
+ * @public
15
+ */
16
+ export function useClosingDelay(waitMs) {
17
+ const clock = useRef(null);
18
+ const turnOff = useCallback(() => {
19
+ if (clock.current) {
20
+ clearTimeout(clock.current);
21
+ clock.current = null;
22
+ }
23
+ }, []);
24
+ useEffect(() => turnOff, [turnOff]);
25
+ return useCallback((todo) => {
26
+ turnOff();
27
+ const ms = waitMs ?? (prefersReducedMotion() ? 0 : POPUP_CLOSE_MS);
28
+ clock.current = setTimeout(() => { clock.current = null; todo?.(); }, ms);
29
+ }, [turnOff, waitMs]);
30
+ }
@@ -0,0 +1,9 @@
1
+ /**
2
+ * **망이 붙어 있나**(말귀 청 (437) ㉲ — 말귀 앱에서 옮겨 왔다, 2026-11-13).
3
+ *
4
+ * `navigator.onLine` 이 **참이라고 인터넷이 되는 것은 아니다**(공유기에만 붙은 상태도 참). 거짓일 때만 믿는다 — 그래서 이 값은
5
+ * "끊겼다" 를 말하는 데만 쓰고 "붙었다" 를 보장하는 데는 안 쓴다. `useSyncExternalStore` 로 그릴 때마다 바깥 값을 읽어,
6
+ * 첫 그림과 효과 사이에 바뀐 것을 놓치지 않는다. `navigator` 가 없는 터전(서버)에서는 붙은 것으로 친다 — 틀린 띠가 더 나쁘다.
7
+ * @public
8
+ */
9
+ export declare function useOnline(): boolean;
@@ -0,0 +1,23 @@
1
+ 'use client';
2
+ import { useSyncExternalStore } from 'react';
3
+ function subscribe(onChange) {
4
+ window.addEventListener('online', onChange);
5
+ window.addEventListener('offline', onChange);
6
+ return () => {
7
+ window.removeEventListener('online', onChange);
8
+ window.removeEventListener('offline', onChange);
9
+ };
10
+ }
11
+ /** 거짓일 때만 끊긴 것으로 — `undefined` 는 모르는 것이라 붙은 쪽으로 읽는다 */
12
+ const read = () => typeof navigator === 'undefined' || navigator.onLine !== false;
13
+ /**
14
+ * **망이 붙어 있나**(말귀 청 (437) ㉲ — 말귀 앱에서 옮겨 왔다, 2026-11-13).
15
+ *
16
+ * `navigator.onLine` 이 **참이라고 인터넷이 되는 것은 아니다**(공유기에만 붙은 상태도 참). 거짓일 때만 믿는다 — 그래서 이 값은
17
+ * "끊겼다" 를 말하는 데만 쓰고 "붙었다" 를 보장하는 데는 안 쓴다. `useSyncExternalStore` 로 그릴 때마다 바깥 값을 읽어,
18
+ * 첫 그림과 효과 사이에 바뀐 것을 놓치지 않는다. `navigator` 가 없는 터전(서버)에서는 붙은 것으로 친다 — 틀린 띠가 더 나쁘다.
19
+ * @public
20
+ */
21
+ export function useOnline() {
22
+ return useSyncExternalStore(subscribe, read, () => true);
23
+ }
@@ -0,0 +1,11 @@
1
+ import { type RefObject } from 'react';
2
+ /**
3
+ * **밖을 누르면 접는다** — 펴 둔 목록 · 판을 닫는 한 가지 배선(말귀 청 (437) ㉲ — 말귀 앱에서 옮겨 왔다, 2026-11-13).
4
+ *
5
+ * · **`mousedown` 에서 닫는다**(`click` 이 아니라) — 누르는 순간 닫혀야 그 아래 것이 눌리지 않는다. 통 **안**이면 아무 일도 안 한다.
6
+ * · **펴 있을 때만 듣는다** — 접힌 목록 수십 개가 문서 듣개를 물고 있을 까닭이 없다.
7
+ * · 닫는 함수는 ref 로 들고 최신 것을 부른다 — 인라인 함수를 넘겨도 렌더마다 듣개를 다시 걸지 않는다.
8
+ * 닻이 있는 떠 있는 메뉴는 `useAnchoredMenu` 가 같은 일을 한다 — 이것은 제자리에 펴지는 목록 · 판 몫이다.
9
+ * @public
10
+ */
11
+ export declare function useOutsideClose(isOpen: boolean, boxRef: RefObject<HTMLElement | null>, close: () => void): void;
@@ -0,0 +1,23 @@
1
+ 'use client';
2
+ import { useEffect } from 'react';
3
+ import { useLatestRef } from './useLatestRef';
4
+ /**
5
+ * **밖을 누르면 접는다** — 펴 둔 목록 · 판을 닫는 한 가지 배선(말귀 청 (437) ㉲ — 말귀 앱에서 옮겨 왔다, 2026-11-13).
6
+ *
7
+ * · **`mousedown` 에서 닫는다**(`click` 이 아니라) — 누르는 순간 닫혀야 그 아래 것이 눌리지 않는다. 통 **안**이면 아무 일도 안 한다.
8
+ * · **펴 있을 때만 듣는다** — 접힌 목록 수십 개가 문서 듣개를 물고 있을 까닭이 없다.
9
+ * · 닫는 함수는 ref 로 들고 최신 것을 부른다 — 인라인 함수를 넘겨도 렌더마다 듣개를 다시 걸지 않는다.
10
+ * 닻이 있는 떠 있는 메뉴는 `useAnchoredMenu` 가 같은 일을 한다 — 이것은 제자리에 펴지는 목록 · 판 몫이다.
11
+ * @public
12
+ */
13
+ export function useOutsideClose(isOpen, boxRef, close) {
14
+ const latest = useLatestRef(close);
15
+ useEffect(() => {
16
+ if (!isOpen)
17
+ return;
18
+ const onDown = (e) => { if (!boxRef.current?.contains(e.target))
19
+ latest.current(); };
20
+ document.addEventListener('mousedown', onDown);
21
+ return () => document.removeEventListener('mousedown', onDown);
22
+ }, [isOpen, boxRef, latest]);
23
+ }
@@ -0,0 +1,19 @@
1
+ /** @public 목록 쪽당 개수의 기본값 — 말귀 회원앱 목록들이 쓰던 넷 */
2
+ export declare const DEFAULT_PAGE_SIZES: readonly [10, 25, 50, 100];
3
+ /**
4
+ * **"N개씩 보기" 보기 목록** — `Toolbar` 의 `pageSize.options` · `Dropdown` 에 그대로 넘긴다(말귀 청 (437) ㉳ⓐ, 2026-11-13).
5
+ *
6
+ * 코어가 `ListPopup` 안에서 `common.pageSizeLabel` 로 이 목록을 짓고도 내주지 않아, 말귀 앱 · 어드민이 사전 열쇠 세 벌과
7
+ * 박은 한국어로 같은 것을 다시 지었다. 문구는 사전(`common.pageSizeLabel` — `{{n}}개씩 보기` · `Show {{n}}`) 한 벌이고,
8
+ * 값(몇 개씩)은 화면마다 다르니 받는다. 값은 문자열로 돌려준다(드롭다운 값이 문자열이다).
9
+ *
10
+ * ```tsx
11
+ * const options = usePageSizeOptions() // 10 · 25 · 50 · 100
12
+ * const cards = usePageSizeOptions([12, 24, 48]) // 화면마다 다른 값
13
+ * ```
14
+ * @public
15
+ */
16
+ export declare function usePageSizeOptions(counts?: readonly number[]): {
17
+ value: string;
18
+ label: string;
19
+ }[];
@@ -0,0 +1,25 @@
1
+ 'use client';
2
+ import { useMemo } from 'react';
3
+ import { useTranslation } from 'react-i18next';
4
+ /** @public 목록 쪽당 개수의 기본값 — 말귀 회원앱 목록들이 쓰던 넷 */
5
+ export const DEFAULT_PAGE_SIZES = [10, 25, 50, 100];
6
+ /**
7
+ * **"N개씩 보기" 보기 목록** — `Toolbar` 의 `pageSize.options` · `Dropdown` 에 그대로 넘긴다(말귀 청 (437) ㉳ⓐ, 2026-11-13).
8
+ *
9
+ * 코어가 `ListPopup` 안에서 `common.pageSizeLabel` 로 이 목록을 짓고도 내주지 않아, 말귀 앱 · 어드민이 사전 열쇠 세 벌과
10
+ * 박은 한국어로 같은 것을 다시 지었다. 문구는 사전(`common.pageSizeLabel` — `{{n}}개씩 보기` · `Show {{n}}`) 한 벌이고,
11
+ * 값(몇 개씩)은 화면마다 다르니 받는다. 값은 문자열로 돌려준다(드롭다운 값이 문자열이다).
12
+ *
13
+ * ```tsx
14
+ * const options = usePageSizeOptions() // 10 · 25 · 50 · 100
15
+ * const cards = usePageSizeOptions([12, 24, 48]) // 화면마다 다른 값
16
+ * ```
17
+ * @public
18
+ */
19
+ export function usePageSizeOptions(counts = DEFAULT_PAGE_SIZES) {
20
+ const { t } = useTranslation();
21
+ const key = counts.join(',');
22
+ return useMemo(() => counts.map(n => ({ value: String(n), label: t('common.pageSizeLabel', { n, defaultValue: '{{n}}개씩 보기' }) })),
23
+ // eslint-disable-next-line react-hooks/exhaustive-deps -- 값 목록은 내용(key)으로 견준다 — 부르는 쪽이 매 그림 새 배열을 넘겨도 다시 안 짓는다
24
+ [key, t]);
25
+ }
@@ -0,0 +1,14 @@
1
+ /**
2
+ * **쪽이 숨는 순간 초안을 바로 적는다**(말귀 청 (437) ㉲ — 말귀 앱에서 옮겨 왔다, 2026-11-13).
3
+ *
4
+ * 고치던 것을 늦춰(디바운스) 적는 화면은, 마지막 손질 뒤 그 짬 안에 탭이 사라지면 그 손질만 빠진다. 폰에서는 드물지 않다 —
5
+ * 글자를 치고 바로 홈 단추를 누르거나 전화가 와서 앱이 뒤로 밀린다. 묻는 길(`beforeunload`)은 iOS 사파리가 거의 안 쏴서 못 쓴다.
6
+ *
7
+ * · `visibilitychange` → `hidden` 이 폰에서 실제로 오는 신호다(홈 · 앱 전환 · 화면 잠금).
8
+ * · `pagehide` 는 탭을 닫거나 옮길 때 · 뒤로-앞으로 캐시로 들어갈 때 와서 `hidden` 이 안 오는 경우를 메운다.
9
+ * 둘 다 올 수 있다 — 같은 값을 두 번 적어도 해가 없게(멱등하게) 적는다.
10
+ *
11
+ * **여기서 비동기를 하지 않는다** — 숨는 순간 브라우저는 약속이 끝나기를 안 기다린다. `localStorage` 처럼 그 자리에서 끝나는 쓰기만.
12
+ * @public
13
+ */
14
+ export declare function useSaveOnHide(save: () => void, enabled?: boolean): void;
@@ -0,0 +1,32 @@
1
+ 'use client';
2
+ import { useEffect } from 'react';
3
+ import { useLatestRef } from './useLatestRef';
4
+ /**
5
+ * **쪽이 숨는 순간 초안을 바로 적는다**(말귀 청 (437) ㉲ — 말귀 앱에서 옮겨 왔다, 2026-11-13).
6
+ *
7
+ * 고치던 것을 늦춰(디바운스) 적는 화면은, 마지막 손질 뒤 그 짬 안에 탭이 사라지면 그 손질만 빠진다. 폰에서는 드물지 않다 —
8
+ * 글자를 치고 바로 홈 단추를 누르거나 전화가 와서 앱이 뒤로 밀린다. 묻는 길(`beforeunload`)은 iOS 사파리가 거의 안 쏴서 못 쓴다.
9
+ *
10
+ * · `visibilitychange` → `hidden` 이 폰에서 실제로 오는 신호다(홈 · 앱 전환 · 화면 잠금).
11
+ * · `pagehide` 는 탭을 닫거나 옮길 때 · 뒤로-앞으로 캐시로 들어갈 때 와서 `hidden` 이 안 오는 경우를 메운다.
12
+ * 둘 다 올 수 있다 — 같은 값을 두 번 적어도 해가 없게(멱등하게) 적는다.
13
+ *
14
+ * **여기서 비동기를 하지 않는다** — 숨는 순간 브라우저는 약속이 끝나기를 안 기다린다. `localStorage` 처럼 그 자리에서 끝나는 쓰기만.
15
+ * @public
16
+ */
17
+ export function useSaveOnHide(save, enabled = true) {
18
+ const latest = useLatestRef(save);
19
+ useEffect(() => {
20
+ if (!enabled)
21
+ return;
22
+ const flush = () => { latest.current(); };
23
+ const onVisibility = () => { if (document.visibilityState === 'hidden')
24
+ flush(); };
25
+ document.addEventListener('visibilitychange', onVisibility);
26
+ window.addEventListener('pagehide', flush);
27
+ return () => {
28
+ document.removeEventListener('visibilitychange', onVisibility);
29
+ window.removeEventListener('pagehide', flush);
30
+ };
31
+ }, [enabled, latest]);
32
+ }
@@ -0,0 +1,12 @@
1
+ /**
2
+ * **켜 둔 동안 폰 화면이 저절로 꺼지지 않게 한다**(말귀 청 (437) ㉲ — 말귀 앱에서 옮겨 왔다, 2026-11-13).
3
+ *
4
+ * 훈련은 "듣고 → 고르기" 라 손이 화면에 닿지 않는 구간이 길다 — 폰의 화면 꺼짐(30초 · 1분)이 먼저 와서 소리는 나는데 화면이
5
+ * 꺼지고, 깨우면 잠금 화면이 가로막는다.
6
+ *
7
+ * · `active` 인 동안 `wakeLock.request('screen')` 을 잡는다. 못 잡으면(저전력 모드 · 안 되는 브라우저) **조용히** 지나간다.
8
+ * · 탭이 숨겨지면 브라우저가 알아서 놓는다. **다시 보이면 다시 잡는다**(`visibilitychange`).
9
+ * · 끝나면 놓는다. 잡는 중에 끝났으면 잡힌 것을 바로 놓는다(언마운트 뒤에 남는 잠금이 없게).
10
+ * @public
11
+ */
12
+ export declare function useScreenWakeLock(active: boolean): void;
@@ -0,0 +1,53 @@
1
+ 'use client';
2
+ import { useEffect } from 'react';
3
+ /**
4
+ * **켜 둔 동안 폰 화면이 저절로 꺼지지 않게 한다**(말귀 청 (437) ㉲ — 말귀 앱에서 옮겨 왔다, 2026-11-13).
5
+ *
6
+ * 훈련은 "듣고 → 고르기" 라 손이 화면에 닿지 않는 구간이 길다 — 폰의 화면 꺼짐(30초 · 1분)이 먼저 와서 소리는 나는데 화면이
7
+ * 꺼지고, 깨우면 잠금 화면이 가로막는다.
8
+ *
9
+ * · `active` 인 동안 `wakeLock.request('screen')` 을 잡는다. 못 잡으면(저전력 모드 · 안 되는 브라우저) **조용히** 지나간다.
10
+ * · 탭이 숨겨지면 브라우저가 알아서 놓는다. **다시 보이면 다시 잡는다**(`visibilitychange`).
11
+ * · 끝나면 놓는다. 잡는 중에 끝났으면 잡힌 것을 바로 놓는다(언마운트 뒤에 남는 잠금이 없게).
12
+ * @public
13
+ */
14
+ export function useScreenWakeLock(active) {
15
+ useEffect(() => {
16
+ if (!active || typeof navigator === 'undefined')
17
+ return;
18
+ const wakeLock = navigator.wakeLock;
19
+ if (!wakeLock)
20
+ return;
21
+ let sentinel = null;
22
+ let stopped = false;
23
+ const acquire = async () => {
24
+ if (stopped || sentinel || document.visibilityState !== 'visible')
25
+ return;
26
+ try {
27
+ const got = await wakeLock.request('screen');
28
+ if (stopped) {
29
+ void got.release().catch(() => { });
30
+ return;
31
+ }
32
+ sentinel = got;
33
+ got.addEventListener('release', () => { if (sentinel === got)
34
+ sentinel = null; });
35
+ }
36
+ catch {
37
+ /* 저전력 모드 · 권한 거절 — 화면이 평소처럼 꺼질 뿐이다 */
38
+ }
39
+ };
40
+ const onVisible = () => { if (document.visibilityState === 'visible')
41
+ void acquire(); };
42
+ void acquire();
43
+ document.addEventListener('visibilitychange', onVisible);
44
+ return () => {
45
+ stopped = true;
46
+ document.removeEventListener('visibilitychange', onVisible);
47
+ if (sentinel) {
48
+ void sentinel.release().catch(() => { });
49
+ sentinel = null;
50
+ }
51
+ };
52
+ }, [active]);
53
+ }
@@ -35,3 +35,9 @@ export type { SoundCompassMode, SoundCompassPhase, SoundCompassExam, UseSoundCom
35
35
  export { useInlineSvg } from './hooks/useInlineSvg';
36
36
  export * from './hooks/useFolderBrowse';
37
37
  export * from './hooks/useCardDragToGroup';
38
+ export * from './hooks/usePageSizeOptions';
39
+ export * from './hooks/useSaveOnHide';
40
+ export * from './hooks/useScreenWakeLock';
41
+ export * from './hooks/useOnline';
42
+ export * from './hooks/useOutsideClose';
43
+ export * from './hooks/useClosingDelay';
@@ -40,3 +40,10 @@ export { useInlineSvg } from './hooks/useInlineSvg';
40
40
  /* 폴더 화면(말귀 청 (437) ㉮, 2026-11-13) — 지금 연 폴더 · 카드를 끌어 폴더에 놓기 */
41
41
  export * from './hooks/useFolderBrowse';
42
42
  export * from './hooks/useCardDragToGroup';
43
+ export * from './hooks/usePageSizeOptions'; // "N개씩 보기" 목록(말귀 청 (437) ㉳ⓐ)
44
+ /* 브라우저 생애 · 닫힘 기다리기(말귀 청 (437) ㉲ ㉳ⓑ, 2026-11-13) */
45
+ export * from './hooks/useSaveOnHide';
46
+ export * from './hooks/useScreenWakeLock';
47
+ export * from './hooks/useOnline';
48
+ export * from './hooks/useOutsideClose';
49
+ export * from './hooks/useClosingDelay';
@@ -0,0 +1,21 @@
1
+ /**
2
+ * **화면이 고른 한국 시각(벽시계)을 서버가 아는 순간으로, 또 그 반대로**(말귀 청 (437) ㉳ⓒ — 말귀 앱에서 옮겨 왔다, 2026-11-13).
3
+ *
4
+ * `timestamptz` 칸에 시간대 표기가 없는 문자열(`2026-09-06T12:55:00`)을 보내면 서버가 UTC 로 읽어 **9시간이 밀린다**
5
+ * (말귀 실측: 12:55 → 21:55, 저녁 것은 날짜까지 하루). 기기 시간대가 아니라 **한국 시각**으로 읽는다 — 뉴욕 기기에서
6
+ * 12:55 를 골라도 KST 12:55 다. 한국은 서머타임이 없어 +09:00 한 값이다. KST 날짜 셈의 다른 식구는 `utils/date.ts`.
7
+ */
8
+ /** @public `YYYY-MM-DD` + `HH:mm`(한국 시각) → `Z` 붙은 ISO. 못 읽을 값(2월 31일 · 25시 …)이면 `null` */
9
+ export declare function kstToIso(date: string, time: string): string | null;
10
+ /** @public 연 · 월 · 일 · 시 · 분 칸(한국 시각) */
11
+ export interface KstParts {
12
+ year: string;
13
+ month: string;
14
+ day: string;
15
+ hour: string;
16
+ minute: string;
17
+ }
18
+ /** @public 칸(한국 시각)이 가리키는 순간. 못 읽으면 Invalid Date */
19
+ export declare function kstPartsAt(p: KstParts): Date;
20
+ /** @public 그 순간의 한국 시각을 칸으로 — 기본은 지금. 두 자리로 채운다 */
21
+ export declare function kstNowParts(now?: Date): KstParts;