@ihabdevteam/core 0.442.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 (44) hide show
  1. package/CHANGELOG.md +14 -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 +247 -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/Popup.js +2 -1
  18. package/dist/packages/core/src/components/ScoreMarkCounts.css +9 -0
  19. package/dist/packages/core/src/components/ScoreMarkCounts.d.ts +19 -0
  20. package/dist/packages/core/src/components/ScoreMarkCounts.js +16 -0
  21. package/dist/packages/core/src/components.d.ts +10 -0
  22. package/dist/packages/core/src/components.js +7 -0
  23. package/dist/packages/core/src/hooks/useClosingDelay.d.ts +12 -0
  24. package/dist/packages/core/src/hooks/useClosingDelay.js +30 -0
  25. package/dist/packages/core/src/hooks/useOnline.d.ts +9 -0
  26. package/dist/packages/core/src/hooks/useOnline.js +23 -0
  27. package/dist/packages/core/src/hooks/useOutsideClose.d.ts +11 -0
  28. package/dist/packages/core/src/hooks/useOutsideClose.js +23 -0
  29. package/dist/packages/core/src/hooks/useSaveOnHide.d.ts +14 -0
  30. package/dist/packages/core/src/hooks/useSaveOnHide.js +32 -0
  31. package/dist/packages/core/src/hooks/useScreenWakeLock.d.ts +12 -0
  32. package/dist/packages/core/src/hooks/useScreenWakeLock.js +53 -0
  33. package/dist/packages/core/src/hooks.d.ts +5 -0
  34. package/dist/packages/core/src/hooks.js +6 -0
  35. package/dist/packages/core/src/utils/kstDateTime.d.ts +21 -0
  36. package/dist/packages/core/src/utils/kstDateTime.js +38 -0
  37. package/dist/packages/core/src/utils/popupTiming.d.ts +7 -0
  38. package/dist/packages/core/src/utils/popupTiming.js +7 -0
  39. package/dist/packages/core/src/utils.d.ts +2 -0
  40. package/dist/packages/core/src/utils.js +1 -0
  41. package/dist/packages/core/src/version.d.ts +1 -1
  42. package/dist/packages/core/src/version.js +1 -1
  43. package/dist/utils.cjs.js +166 -166
  44. package/package.json +1 -1
@@ -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) {
@@ -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';
@@ -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';
@@ -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,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
+ }
@@ -36,3 +36,8 @@ export { useInlineSvg } from './hooks/useInlineSvg';
36
36
  export * from './hooks/useFolderBrowse';
37
37
  export * from './hooks/useCardDragToGroup';
38
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';
@@ -41,3 +41,9 @@ export { useInlineSvg } from './hooks/useInlineSvg';
41
41
  export * from './hooks/useFolderBrowse';
42
42
  export * from './hooks/useCardDragToGroup';
43
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;
@@ -0,0 +1,38 @@
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
+ const KST_OFFSET_H = 9;
9
+ /** @public `YYYY-MM-DD` + `HH:mm`(한국 시각) → `Z` 붙은 ISO. 못 읽을 값(2월 31일 · 25시 …)이면 `null` */
10
+ export function kstToIso(date, time) {
11
+ const day = /^(\d{4})-(\d{2})-(\d{2})$/.exec(date);
12
+ const hm = /^(\d{1,2}):(\d{2})$/.exec(time);
13
+ if (!day || !hm)
14
+ return null;
15
+ const [y, m, d] = [Number(day[1]), Number(day[2]), Number(day[3])];
16
+ const [hh, mm] = [Number(hm[1]), Number(hm[2])];
17
+ if (hh > 23 || mm > 59)
18
+ return null;
19
+ /* 2월 31일은 Date 가 조용히 다음 달로 넘긴다 — 넘어갔으면 못 읽은 것. 조용히 다른 날로 저장하느니 안 보내는 편이 낫다 */
20
+ const calendar = new Date(Date.UTC(y, m - 1, d));
21
+ if (calendar.getUTCMonth() !== m - 1 || calendar.getUTCDate() !== d)
22
+ return null;
23
+ return new Date(Date.UTC(y, m - 1, d, hh - KST_OFFSET_H, mm)).toISOString();
24
+ }
25
+ /** @public 칸(한국 시각)이 가리키는 순간. 못 읽으면 Invalid Date */
26
+ export function kstPartsAt(p) {
27
+ const iso = kstToIso(`${p.year}-${p.month.padStart(2, '0')}-${p.day.padStart(2, '0')}`, `${p.hour}:${p.minute.padStart(2, '0')}`);
28
+ return new Date(iso ?? NaN);
29
+ }
30
+ /** @public 그 순간의 한국 시각을 칸으로 — 기본은 지금. 두 자리로 채운다 */
31
+ export function kstNowParts(now = new Date()) {
32
+ const korea = new Date(now.getTime() + KST_OFFSET_H * 3600_000);
33
+ const two = (n) => String(n).padStart(2, '0');
34
+ return {
35
+ year: String(korea.getUTCFullYear()), month: two(korea.getUTCMonth() + 1), day: two(korea.getUTCDate()),
36
+ hour: two(korea.getUTCHours()), minute: two(korea.getUTCMinutes()),
37
+ };
38
+ }
@@ -0,0 +1,7 @@
1
+ /**
2
+ * **`Popup` 이 사라지는 데 걸리는 시간** — `.popup--closing { transition: opacity 260ms }` 과 닫힘 타이머가 이 수를 쓴다
3
+ * (말귀 청 (437) ㉳ⓑ, 2026-11-13 — 앱이 이 수를 베껴 들고 "창이 다 사라진 뒤에 일을 치르려" 기다렸다. 코어가 바꾸면 조용히 어긋났다).
4
+ * 움직임 줄이기에서는 `Popup` 이 0 으로 닫는다 — 기다릴 때는 `useClosingDelay` 를 쓰면 그것까지 따른다.
5
+ * @public
6
+ */
7
+ export declare const POPUP_CLOSE_MS = 260;
@@ -0,0 +1,7 @@
1
+ /**
2
+ * **`Popup` 이 사라지는 데 걸리는 시간** — `.popup--closing { transition: opacity 260ms }` 과 닫힘 타이머가 이 수를 쓴다
3
+ * (말귀 청 (437) ㉳ⓑ, 2026-11-13 — 앱이 이 수를 베껴 들고 "창이 다 사라진 뒤에 일을 치르려" 기다렸다. 코어가 바꾸면 조용히 어긋났다).
4
+ * 움직임 줄이기에서는 `Popup` 이 0 으로 닫는다 — 기다릴 때는 `useClosingDelay` 를 쓰면 그것까지 따른다.
5
+ * @public
6
+ */
7
+ export const POPUP_CLOSE_MS = 260;
@@ -25,6 +25,8 @@ export { reorderArray, shuffle, sample } from './utils/array';
25
25
  export { getErrorMessage, toUserErrorMessage, isNetworkErrorMessage, NETWORK_ERROR_MESSAGE } from './utils/errorMessage';
26
26
  export { sortToValue, parseSortValue } from './utils/sortValue';
27
27
  export { folderLeaf, folderParent, folderJoin, isFolderNameOk, isInFolder, withAncestors, folderChildren, folderTrail, folderTree, folderMoved, canMoveFolder, folderMoveVerdict, } from './utils/folderPath';
28
+ export { kstToIso, kstPartsAt, kstNowParts } from './utils/kstDateTime';
29
+ export type { KstParts } from './utils/kstDateTime';
28
30
  export { folderMenuItems } from './utils/folderMenu';
29
31
  export type { FolderMenuLine } from './utils/folderMenu';
30
32
  export { escapeCsvField, downloadCsvText } from './utils/csv';
@@ -24,6 +24,7 @@ export { getErrorMessage, toUserErrorMessage, isNetworkErrorMessage, NETWORK_ERR
24
24
  export { sortToValue, parseSortValue } from './utils/sortValue';
25
25
  /* 폴더 안의 폴더 — 이름을 길로 적는 셈(말귀 청 (435), 2026-11-13). 그리는 조각은 `FolderHead` 식구다 */
26
26
  export { folderLeaf, folderParent, folderJoin, isFolderNameOk, isInFolder, withAncestors, folderChildren, folderTrail, folderTree, folderMoved, canMoveFolder, folderMoveVerdict, } from './utils/folderPath';
27
+ export { kstToIso, kstPartsAt, kstNowParts } from './utils/kstDateTime'; // 한국 벽시계 ↔ 순간(말귀 청 (437) ㉳ⓒ)
27
28
  export { folderMenuItems } from './utils/folderMenu'; // 폴더 메뉴의 줄(말귀 청 (437) ㉮)
28
29
  export { escapeCsvField, downloadCsvText } from './utils/csv';
29
30
  export { setWordPool, getWordPool } from './utils/wordPool';
@@ -46,4 +46,4 @@
46
46
  *
47
47
  * 값은 손으로 적고 `test/coreVersion.test.ts` 가 package.json 과 어긋나면 운다.
48
48
  */
49
- export declare const CORE_VERSION = "0.442.0";
49
+ export declare const CORE_VERSION = "0.443.0";
@@ -46,4 +46,4 @@
46
46
  *
47
47
  * 값은 손으로 적고 `test/coreVersion.test.ts` 가 package.json 과 어긋나면 운다.
48
48
  */
49
- export const CORE_VERSION = '0.442.0';
49
+ export const CORE_VERSION = '0.443.0';