@ihabdevteam/core 0.150.0 → 0.151.0

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

@@ -52,8 +52,14 @@ function lockBodyScrollImpl(withPadding) {
             paddingLockCount = Math.max(0, paddingLockCount - 1);
             // withPadding 오버레이가 모두 닫히면 즉시 여백을 복원한다 — 남아 있는 일반 팝업은
             // scrollbar-gutter 여백을 없앨 이유가 없다.
-            if (paddingLockCount === 0)
-                document.body.style.paddingRight = prevPaddingRight;
+            /* 원래 값이 없었으면 속성을 **지운다** — '' 대입은 "되돌림" 이 아니라 "빈 값을 쓴다" 로 읽혀, 인라인 스타일을 다루는
+               도구·다른 코드가 남은 선언으로 볼 수 있었다 */
+            if (paddingLockCount === 0) {
+                if (prevPaddingRight)
+                    document.body.style.paddingRight = prevPaddingRight;
+                else
+                    document.body.style.removeProperty('padding-right');
+            }
         }
         if (lockCount === 0 && hasDoc) {
             document.body.style.overflow = prevOverflow;

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

@@ -2,3 +2,15 @@
 export declare function rememberFocusReturn(panel: Element | null, previouslyFocused: HTMLElement | null): void;
 /** 실제로 돌려줄 곳 — 문서에 붙어 있으면 그대로, 떼어졌으면 그것을 품었던 창이 적어 둔 곳을 따라간다 */
 export declare function resolveFocusReturn(previouslyFocused: HTMLElement | null): HTMLElement | null;
+/**
+ * 사라지거나 inert 가 되는 영역(BulkBar·닫힌 Alert·NoticeBox·UpdateAlert) **안에 포커스가 있을 때** 바깥으로 옮긴다 —
+ * 그냥 두면 포커스가 body 로 떨어져 다음 Tab 이 문서 맨 앞에서 시작했다.
+ *
+ * 1. 그 영역을 연 요소(`opener` — 영역이 나타날 때 포커스였던 곳)가 아직 받을 수 있으면 그곳
+ * 2. 없으면 문서 순서로 **영역 바로 앞의** 포커스 받을 수 있는 요소
+ * 3. 앞에 없으면 뒤의 첫 요소
+ *
+ * `container` 는 아직 문서에 붙어 있어야 순서를 잰다 — 떼기 전에 부르거나 `anchor`(자리를 대신 잴 요소)를 준다.
+ * 옮긴 요소를 돌려준다(못 옮기면 null).
+ */
+export declare function moveFocusOutside(container: Element | null, opener?: Element | null, anchor?: Element | null): HTMLElement | null;

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

@@ -1,3 +1,5 @@
+'use client';
+import { FOCUSABLE_SELECTOR } from './useFocusTrap';
 /**
  * 창(Popup·Dialog·TrainingPagePopup)이 닫힐 때 포커스를 돌려줄 곳 — 창끼리 한 표를 쓴다.
  *
@@ -25,3 +27,50 @@ export function resolveFocusReturn(previouslyFocused) {
     }
     return 대상;
 }
+/* 포커스를 받을 수 있는가 — 붙어 있고, 막히지 않았고, inert·aria-hidden·hidden 아래가 아니다(레이아웃은 재지 않는다: 시험 환경에 없다) */
+function 받을수있나(el) {
+    if (!el || !el.isConnected || el === document.body)
+        return false;
+    if (typeof el.focus !== 'function')
+        return false;
+    if (el.disabled)
+        return false;
+    if (el instanceof HTMLInputElement && el.type === 'hidden')
+        return false;
+    if (el.closest('[inert],[aria-hidden="true"],[hidden]'))
+        return false;
+    return true;
+}
+/**
+ * 사라지거나 inert 가 되는 영역(BulkBar·닫힌 Alert·NoticeBox·UpdateAlert) **안에 포커스가 있을 때** 바깥으로 옮긴다 —
+ * 그냥 두면 포커스가 body 로 떨어져 다음 Tab 이 문서 맨 앞에서 시작했다.
+ *
+ * 1. 그 영역을 연 요소(`opener` — 영역이 나타날 때 포커스였던 곳)가 아직 받을 수 있으면 그곳
+ * 2. 없으면 문서 순서로 **영역 바로 앞의** 포커스 받을 수 있는 요소
+ * 3. 앞에 없으면 뒤의 첫 요소
+ *
+ * `container` 는 아직 문서에 붙어 있어야 순서를 잰다 — 떼기 전에 부르거나 `anchor`(자리를 대신 잴 요소)를 준다.
+ * 옮긴 요소를 돌려준다(못 옮기면 null).
+ */
+export function moveFocusOutside(container, opener, anchor) {
+    const 기준 = container?.isConnected ? container : anchor?.isConnected ? anchor : null;
+    if (받을수있나(opener) && !(container && container.contains(opener))) {
+        opener.focus();
+        return opener;
+    }
+    if (!기준)
+        return null;
+    const 모두 = Array.from(document.querySelectorAll(FOCUSABLE_SELECTOR))
+        .filter((el) => !(container && container.contains(el)) && 받을수있나(el));
+    let 앞 = null;
+    let 뒤 = null;
+    for (const el of 모두) {
+        if (기준.compareDocumentPosition(el) & Node.DOCUMENT_POSITION_PRECEDING)
+            앞 = el;
+        else if (!뒤)
+            뒤 = el;
+    }
+    const 대상 = 앞 ?? 뒤;
+    대상?.focus();
+    return 대상;
+}

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

@@ -0,0 +1,22 @@
+import { type RefObject } from 'react';
+/** 터치 포인터 이벤트인가 */
+export declare function isTouchPointer(e: {
+    pointerType?: string;
+} | null | undefined): boolean;
+/** 방금(1초 안) 화면을 톡했나 — 톡 뒤 따라오는 focus·호환 마우스 이벤트를 거를 때 */
+export declare function recentlyTouched(ms?: number): boolean;
+/**
+ * 톡으로 뒤집는 손잡이. `open` 은 지금 열림, `setOpen(next, el)` 은 열기(el 은 앵커)·닫기.
+ * `rootRef` 는 트리거를 품은 요소 — 이 밖(툴팁 판 `.tooltip-content` 도 제외)을 톡하면 닫는다.
+ *
+ * - `touchPress()` — 지금 누름이 이 트리거 위의 **톡**이었으면 뒤집고 true. 켜진 트리거는 click 에서, 막힌 단추(click 이 안 온다)는
+ *   pointerup 에서 부른다. click 에서 뒤집는 까닭: pointerup 에서 열면 뒤따르는 호환 click 을 툴팁이 "바깥 누름" 으로 받아 곧바로 닫았다.
+ * - 누를 때의 열림은 **문서 캡처 단계에서 먼저** 적어 둔다 — 열린 툴팁의 "바깥 누름 닫기" 가 같은 누름에 먼저 닫아도 다시 열리지 않게.
+ * - 막힌 native 단추에는 포인터 이벤트조차 안 오는 브라우저가 있다 — `rootRef` 의 부모(감싼 요소)에서 touchend 로 받는다(`fallbackOnParent`).
+ */
+export declare function useTouchToggle(open: boolean, setOpen: (next: boolean, el: Element | null) => void, rootRef: RefObject<Element | null>, { enabled, fallbackOnParent }?: {
+    enabled?: boolean;
+    fallbackOnParent?: boolean;
+}): {
+    touchPress: (el?: Element | null) => boolean;
+};

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

@@ -0,0 +1,114 @@
+'use client';
+import { useCallback, useEffect, useRef } from 'react';
+import { useLatestRef } from './useLatestRef';
+/*
+ * 터치에서는 **톡으로 열고 닫는** 툴팁(내부).
+ *
+ * 마우스용으로 짠 호버 툴팁(pointerenter 열기 · pointerleave 닫기 · focus 열기)은 터치에서 이렇게 된다 —
+ * 톡하면 pointerenter 로 열리고 손을 떼자마자 pointerleave 로 닫힌다(터치 포인터는 hover 가 없어 떼면 반드시 leave 가 온다).
+ * Android Chrome 은 이어서 단추에 초점을 줘 focus 로 **다시 열리고**, iOS 는 초점을 안 줘 닫힌 채다. 결국 막힌 단추의 사유·점수 칩
+ * 설명·필터 설명(?)·낱말 정보(i)를 터치 기기에서는 읽을 수 없었다.
+ *
+ * 마우스 동작은 그대로 두고, pointerType 이 touch 일 때만: 들어오고 나감은 무시 · 뗄 때 뒤집기 · 방금 톡으로 온 focus 는 무시 ·
+ * 바깥을 톡하면 닫기.
+ */
+let 마지막터치 = 0;
+let 붙음 = false;
+function 붙이기() {
+    if (붙음 || typeof document === 'undefined')
+        return;
+    붙음 = true;
+    document.addEventListener('pointerdown', (e) => { if (e.pointerType === 'touch')
+        마지막터치 = Date.now(); }, true);
+    document.addEventListener('touchstart', () => { 마지막터치 = Date.now(); }, { capture: true, passive: true });
+}
+붙이기();
+/** 터치 포인터 이벤트인가 */
+export function isTouchPointer(e) {
+    return !!e && e.pointerType === 'touch';
+}
+/** 방금(1초 안) 화면을 톡했나 — 톡 뒤 따라오는 focus·호환 마우스 이벤트를 거를 때 */
+export function recentlyTouched(ms = 1000) {
+    붙이기();
+    return Date.now() - 마지막터치 < ms;
+}
+/**
+ * 톡으로 뒤집는 손잡이. `open` 은 지금 열림, `setOpen(next, el)` 은 열기(el 은 앵커)·닫기.
+ * `rootRef` 는 트리거를 품은 요소 — 이 밖(툴팁 판 `.tooltip-content` 도 제외)을 톡하면 닫는다.
+ *
+ * - `touchPress()` — 지금 누름이 이 트리거 위의 **톡**이었으면 뒤집고 true. 켜진 트리거는 click 에서, 막힌 단추(click 이 안 온다)는
+ *   pointerup 에서 부른다. click 에서 뒤집는 까닭: pointerup 에서 열면 뒤따르는 호환 click 을 툴팁이 "바깥 누름" 으로 받아 곧바로 닫았다.
+ * - 누를 때의 열림은 **문서 캡처 단계에서 먼저** 적어 둔다 — 열린 툴팁의 "바깥 누름 닫기" 가 같은 누름에 먼저 닫아도 다시 열리지 않게.
+ * - 막힌 native 단추에는 포인터 이벤트조차 안 오는 브라우저가 있다 — `rootRef` 의 부모(감싼 요소)에서 touchend 로 받는다(`fallbackOnParent`).
+ */
+export function useTouchToggle(open, setOpen, rootRef, { enabled = true, fallbackOnParent = false } = {}) {
+    const openRef = useLatestRef(open);
+    const setOpenRef = useLatestRef(setOpen);
+    /** 이 트리거 위 톡 누름 때의 열림(null 이면 톡 누름이 아니었다) */
+    const 누를때열림 = useRef(null);
+    const 뒤집은시각 = useRef(0);
+    useEffect(() => {
+        if (!enabled || typeof document === 'undefined')
+            return;
+        const 누름 = (ev) => {
+            const pe = ev;
+            const t = ev.target;
+            const root = rootRef.current;
+            const 안 = !!(t && root && root.contains(t));
+            if (pe.pointerType !== 'touch') {
+                if (안)
+                    누를때열림.current = null;
+                return;
+            }
+            if (안) {
+                누를때열림.current = openRef.current;
+                return;
+            }
+            누를때열림.current = null;
+            if (openRef.current && !(t && t.closest?.('.tooltip-content')))
+                setOpenRef.current(false, root);
+        };
+        document.addEventListener('pointerdown', 누름, true);
+        return () => document.removeEventListener('pointerdown', 누름, true);
+    }, [enabled, rootRef, openRef, setOpenRef]);
+    const touchPress = useCallback((el) => {
+        const 전 = 누를때열림.current;
+        if (전 === null)
+            return false;
+        누를때열림.current = null;
+        뒤집은시각.current = Date.now();
+        setOpenRef.current(!전, el ?? rootRef.current);
+        return true;
+    }, [rootRef, setOpenRef]);
+    /* 막힌 native 단추 — 포인터 이벤트가 안 오면 감싼 요소에서 톡(touchstart→touchend)을 받아 자리로 가린다 */
+    useEffect(() => {
+        if (!enabled || !fallbackOnParent)
+            return;
+        const root = rootRef.current;
+        const parent = root?.parentElement;
+        if (!root || !parent)
+            return;
+        let 시작때열림 = null;
+        const 안에있나 = (e) => {
+            const p = e.changedTouches?.[0];
+            if (!p)
+                return false;
+            const r = root.getBoundingClientRect();
+            return p.clientX >= r.left && p.clientX <= r.right && p.clientY >= r.top && p.clientY <= r.bottom;
+        };
+        const 시작 = (e) => { 시작때열림 = 안에있나(e) ? openRef.current : null; };
+        const 끝 = (e) => {
+            const 전 = 시작때열림;
+            시작때열림 = null;
+            if (전 === null || Date.now() - 뒤집은시각.current < 700 || !안에있나(e))
+                return;
+            누를때열림.current = null;
+            뒤집은시각.current = Date.now();
+            setOpenRef.current(!전, root);
+        };
+        parent.addEventListener('touchstart', 시작, { passive: true });
+        parent.addEventListener('touchend', 끝);
+        return () => { parent.removeEventListener('touchstart', 시작); parent.removeEventListener('touchend', 끝); };
+    }, [enabled, fallbackOnParent, rootRef, openRef, setOpenRef]);
+    return { touchPress };
+}

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

@@ -1,10 +1,10 @@
 import { type CSSProperties, type RefObject } from 'react';
 export interface UseAnchoredMenuOptions {
-    /** 트리거의 getBoundingClientRect()로부터 메뉴에 적용할 style을 계산 */
-    computeStyle: (triggerRect: DOMRect) => CSSProperties;
+    /** 트리거의 getBoundingClientRect()로부터 메뉴에 적용할 style을 계산. 둘째 인자는 트리거 요소(층 계산 `anchoredMenuZIndex` 등에 쓴다) */
+    computeStyle: (triggerRect: DOMRect, trigger: HTMLElement) => CSSProperties;
     /** 열려있는 동안 스크롤 발생 시 동작 (메뉴 내부 스크롤은 항상 무시) — 기본 'close' */
     onScroll?: 'close' | 'reposition' | 'ignore';
-    /** 열려있는 동안 윈도우 리사이즈 발생 시 동작 — 기본 'close' */
+    /** 열려있는 동안 윈도우 리사이즈·기기 회전(orientationchange) 발생 시 동작 — 기본 'close' */
     onResize?: 'close' | 'reposition' | 'ignore';
     /** 바깥클릭 판정에서 제외할 CSS selector (예: 메뉴 안에 중첩 포탈되는 다른 드롭다운) */
     ignoreOutsideClickSelector?: string;
@@ -19,6 +19,15 @@ export interface UseAnchoredMenuResult<Trigger extends HTMLElement, Menu extends
     triggerRef: RefObject<Trigger | null>;
     menuRef: RefObject<Menu | null>;
 }
+/**
+ * body 로 빠지는 메뉴(Dropdown·DatePicker·Header·BottomNav 더보기)의 층.
+ *
+ * 전에는 9999·10000 을 박아 **토스트·알림 위** 에 떴다. 토큰 서열은
+ * 페이지 < BulkBar(`--z-bulk-bar`) < 메뉴(`--z-menu`) < 창(Popup·Dialog `--z-modal`) < 툴팁 < 알림·토스트 다.
+ * 다만 창·훈련 팝업·툴팁·달력 **안에서** 연 메뉴는 그 층보다 위여야 한다 — 메뉴는 body 로 빠지므로
+ * 트리거 조상 가운데 가장 높은 z-index 바로 위(없으면 `--z-menu`)로 둔다. 그 층들은 모두 알림·토스트 아래다.
+ */
+export declare function anchoredMenuZIndex(trigger: Element | null | undefined): string;
 /**
  * 트리거 요소에 fixed 포지션으로 앵커링되는 메뉴/드롭다운/팝오버의 공용 로직.
  * 열림상태 + 위치 계산 + 바깥클릭/스크롤/리사이즈 처리를 담당하고, 렌더링(포탈 등)은

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

@@ -1,6 +1,25 @@
 'use client';
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { pushEsc } from './escStack';
+/**
+ * body 로 빠지는 메뉴(Dropdown·DatePicker·Header·BottomNav 더보기)의 층.
+ *
+ * 전에는 9999·10000 을 박아 **토스트·알림 위** 에 떴다. 토큰 서열은
+ * 페이지 < BulkBar(`--z-bulk-bar`) < 메뉴(`--z-menu`) < 창(Popup·Dialog `--z-modal`) < 툴팁 < 알림·토스트 다.
+ * 다만 창·훈련 팝업·툴팁·달력 **안에서** 연 메뉴는 그 층보다 위여야 한다 — 메뉴는 body 로 빠지므로
+ * 트리거 조상 가운데 가장 높은 z-index 바로 위(없으면 `--z-menu`)로 둔다. 그 층들은 모두 알림·토스트 아래다.
+ */
+export function anchoredMenuZIndex(trigger) {
+    let 가장높은 = 0;
+    if (trigger && typeof window !== 'undefined' && typeof window.getComputedStyle === 'function') {
+        for (let el = trigger; el && el !== document.body && el !== document.documentElement; el = el.parentElement) {
+            const z = parseInt(window.getComputedStyle(el).zIndex, 10);
+            if (!Number.isNaN(z) && z > 가장높은)
+                가장높은 = z;
+        }
+    }
+    return 가장높은 > 0 ? `max(var(--z-menu, 1500), ${가장높은 + 1})` : 'var(--z-menu, 1500)';
+}
 /**
  * 트리거 요소에 fixed 포지션으로 앵커링되는 메뉴/드롭다운/팝오버의 공용 로직.
  * 열림상태 + 위치 계산 + 바깥클릭/스크롤/리사이즈 처리를 담당하고, 렌더링(포탈 등)은
@@ -15,7 +34,7 @@ export function useAnchoredMenu({ computeStyle, onScroll = 'close', onResize = '
     const recalc = useCallback(() => {
         if (!triggerRef.current)
             return;
-        setStyle(computeStyle(triggerRef.current.getBoundingClientRect()));
+        setStyle(computeStyle(triggerRef.current.getBoundingClientRect(), triggerRef.current));
     }, [computeStyle]);
     useEffect(() => {
         if (!open)
@@ -50,15 +69,30 @@ export function useAnchoredMenu({ computeStyle, onScroll = 'close', onResize = '
             else if (onResize === 'close')
                 setOpen(false);
         };
-        if (onResize !== 'ignore')
+        /* 회전(orientationchange)도 함께 — iOS Safari 는 회전 직후 resize 가 늦거나 옛 크기로 오는 일이 있어 회전 뒤 한 번 더 잰다 */
+        let 회전타이머 = null;
+        const handleOrientation = () => {
+            handleResize();
+            if (회전타이머)
+                clearTimeout(회전타이머);
+            회전타이머 = setTimeout(() => { 회전타이머 = null; if (onResize === 'reposition')
+                recalc(); }, 250);
+        };
+        if (onResize !== 'ignore') {
             window.addEventListener('resize', handleResize);
+            window.addEventListener('orientationchange', handleOrientation);
+        }
         return () => {
             document.removeEventListener('mousedown', handleOutsideClick);
             document.removeEventListener('pointerdown', handleOutsideClick);
             if (onScroll !== 'ignore')
                 window.removeEventListener('scroll', handleScroll, true);
-            if (onResize !== 'ignore')
+            if (onResize !== 'ignore') {
                 window.removeEventListener('resize', handleResize);
+                window.removeEventListener('orientationchange', handleOrientation);
+            }
+            if (회전타이머)
+                clearTimeout(회전타이머);
         };
     }, [open, recalc, onScroll, onResize, ignoreOutsideClickSelector]);
     /* ESC 로 닫기 — **공유 ESC 스택**에 올린다(Popup 과 같은 스택). 전에는 document 에서 따로 들어,

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

@@ -2,8 +2,10 @@ import type { TrainingItem } from '../types/training';
 /**
  * 오늘/어제 훈련 선택을 (user, 날짜) 결정적 시드로 계산하는 훅(영속 저장 없음).
  *
- * - resolveSelection은 시드 기반이라 기기/세션 무관 동일 결과
- * - 데이터 미로딩 시 ensureTrainingDataLoaded() 대기 후 재계산
+ * - resolveSelection은 (사용자, 날짜, 유형) 시드 기반이라 기기/세션 무관 동일 결과. 유형마다 시드가 따로라 한 유형 자료가
+ *   바뀌어도 다른 유형 세트는 그대로
+ * - 오늘 세트는 후보가 충분하면 어제 세트와 겹치지 않는다(어제 보기는 어제 실제로 뜬 세트와 같다)
+ * - 데이터 미로딩 시 ensureTrainingDataLoaded() 대기 후 재계산(받는 중에는 새로 부르지 않는다)
  * - 폴링(250ms): 훈련 데이터가 비동기로 채워질 때까지 재시도
  */
 /**

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

@@ -7,8 +7,10 @@ import { hasItems, resolveSelection, } from '../utils/dailySelectionUtils';
 /**
  * 오늘/어제 훈련 선택을 (user, 날짜) 결정적 시드로 계산하는 훅(영속 저장 없음).
  *
- * - resolveSelection은 시드 기반이라 기기/세션 무관 동일 결과
- * - 데이터 미로딩 시 ensureTrainingDataLoaded() 대기 후 재계산
+ * - resolveSelection은 (사용자, 날짜, 유형) 시드 기반이라 기기/세션 무관 동일 결과. 유형마다 시드가 따로라 한 유형 자료가
+ *   바뀌어도 다른 유형 세트는 그대로
+ * - 오늘 세트는 후보가 충분하면 어제 세트와 겹치지 않는다(어제 보기는 어제 실제로 뜬 세트와 같다)
+ * - 데이터 미로딩 시 ensureTrainingDataLoaded() 대기 후 재계산(받는 중에는 새로 부르지 않는다)
  * - 폴링(250ms): 훈련 데이터가 비동기로 채워질 때까지 재시도
  */
 /**
@@ -49,6 +51,8 @@ export function useDailyTrainingSelection(userId) {
         let 적용됨 = false;
         let timer;
         let attempts = 0;
+        let 받는중 = null;
+        let 다음받기 = 0; // 이 attempts 에 이르면 자료 받기를 다시 청한다(2초 = 8틱마다)
         const MAX_ATTEMPTS = 40; // 250ms * 40 = 10초 후 폴링 중단(풀이 영영 비는 경우 무한루프 방지)
         const stop = () => { if (timer !== undefined) {
             clearInterval(timer);
@@ -86,11 +90,22 @@ export function useDailyTrainingSelection(userId) {
             }
             /* 캐시 miss → 데이터 로드 후 새 선택. 로드는 **2초마다 한 번만** 다시 청한다 — 250ms 마다 부르면 받기가 곧바로 실패하는
                배포(형식 오류)에서 10초에 850KB 자료를 40번 받았다. 그 사이 폴링은 선택만 다시 계산한다. */
-            if (attempts % 8 === 0) {
+            /* **받는 중이면 이 틱은 건너뛴다** — 받기는 3초까지 기다리는데 250ms 틱이 그 사이 attempts 가 안 오른 채 들어와
+               ensureTrainingDataLoaded 를 매번 새로 불러, 끝나지 않은 받기마다 3초 타이머가 열두 개씩 쌓였다. 진행 중인 약속을 하나만 둔다. */
+            if (받는중) {
+                if (++attempts >= MAX_ATTEMPTS)
+                    포기();
+                return;
+            } // 건너뛴 틱도 10초 시한에 센다
+            if (attempts >= 다음받기) {
+                다음받기 = attempts + 8;
+                받는중 = ensureTrainingDataLoaded(3000).catch(() => false);
                 try {
-                    await ensureTrainingDataLoaded(3000);
+                    await 받는중;
+                }
+                finally {
+                    받는중 = null;
                 }
-                catch { }
                 if (cancelled)
                     return;
             }
@@ -102,13 +117,10 @@ export function useDailyTrainingSelection(userId) {
             // 데이터가 끝내 차지 않으면 일정 시도 후 중단(빈 선택이라도 로딩 종료)
             // 포기한다. hasData 를 반드시 false 로 되돌린다 — userId 가 바뀌어 다시 돌 때,
             // 앞 사람 것이 성공했다면 true 로 남아 있어 "자료가 있다" 고 거짓말하게 된다.
-            if (++attempts >= MAX_ATTEMPTS) {
-                setLoaded(true);
-                setHasData(false);
-                cancelled = true;
-                stop();
-            }
+            if (++attempts >= MAX_ATTEMPTS)
+                포기();
         };
+        function 포기() { setLoaded(true); setHasData(false); cancelled = true; stop(); }
         /* 포기한 뒤(10초)라도 자료가 도착하면 다시 계산한다 — 느린 회선에서 13초 걸려 받은 회원은 새로고침 전까지 "자료를 못 찾음" 에 남았다 */
         const 자료도착 = () => {
             if (떠남 || 적용됨)

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

@@ -2,14 +2,38 @@
 import { useState, useEffect } from 'react';
 import DOMPurify from 'dompurify';
 import { resolveAssetUrl } from '../utils';
+/* 속성 값이 **문서 밖을 가리키는** url( 을 품었나. `url(#그라데이션)`·`url(#clip)` 처럼 같은 SVG 안의 조각만 가리키는 것은 둔다 —
+   코어 로고 서른여섯 장이 clip-path·fill 로 그것을 쓴다(걷으면 인라인으로 그린 로고가 깨진다).
+   CSS 이스케이프로 url 을 숨긴 꼴(역슬래시 + 괄호)도 걷는다 — 아이콘 속성에 그런 값을 쓸 까닭이 없다. */
+function 바깥url있나(value) {
+    if (value.includes('\\') && value.includes('('))
+        return true;
+    if (!/url\s*\(/i.test(value))
+        return false;
+    const 조각만뺀 = value.replace(/url\(\s*(['"]?)#[^)'"]*\1\s*\)/gi, '');
+    return /url\s*\(/i.test(조각만뺀);
+}
 function sanitizeSvg(raw) {
     if (typeof window === 'undefined')
         return '';
-    return DOMPurify.sanitize(raw, {
-        USE_PROFILES: { svg: true, svgFilters: true },
-        FORBID_TAGS: ['script', 'use'],
-        FORBID_ATTR: ['xlink:href', 'href'],
-    });
+    /* 인라인 SVG 에서 **바깥 자원을 부르는 길** 을 걷는다 — `<style>`(@import·background:url) 과 바깥 url( 이 든 속성(style·fill·filter…).
+       그대로 두면 아이콘 한 장이 제3자 주소로 요청을 보내거나(추적) CSS 로 화면을 덮을 수 있었다.
+       훅은 DOMPurify 전역에 붙으므로 이 한 번의 sanitize 동안만 걸고 곧바로 뗀다(앱의 다른 DOMPurify 쓰임에 새지 않게). */
+    const 훅 = (_node, data) => {
+        if (typeof data.attrValue === 'string' && 바깥url있나(data.attrValue))
+            data.keepAttr = false;
+    };
+    DOMPurify.addHook('uponSanitizeAttribute', 훅);
+    try {
+        return DOMPurify.sanitize(raw, {
+            USE_PROFILES: { svg: true, svgFilters: true },
+            FORBID_TAGS: ['script', 'use', 'style'],
+            FORBID_ATTR: ['xlink:href', 'href'],
+        });
+    }
+    finally {
+        DOMPurify.removeHook('uponSanitizeAttribute', 훅);
+    }
 }
 /** @public */
 export default function useIcon(icon) {

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

@@ -5,6 +5,10 @@
  * 바로 나옵니다. 목록에 없는 이름은 `null` 을 돌려줍니다 — 받아 오지 않으며,
  * 개발 모드에서 이름당 한 번 경고를 남깁니다. URL·에셋 경로도 `null` 입니다.
  *
+ * **`.svg` 경로는 파일 이름으로 lucide 를 먼저 찾는다** — `'/images/brand/check.svg'` 는 `'check'` 로 읽혀 lucide 체크가
+ * 그려진다(파일을 받지 않음). 목록에 그 이름이 없을 때만 Icon 이 파일을 받는다. 옛 브랜드 SVG 경로를 넘기던 화면과 모양을
+ * 맞추려고 **일부러 두는 동작**이다(2026-09-15 결정: 유지). 파일 그림 그대로가 필요하면 lucide 에 없는 파일 이름을 쓴다.
+ *
  * @example
  * const HomeIcon = useLucideIcon('home')
  * return HomeIcon ? <HomeIcon size={20} /> : null

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

@@ -43,6 +43,10 @@ const lazyCache = new Map();
  * 바로 나옵니다. 목록에 없는 이름은 `null` 을 돌려줍니다 — 받아 오지 않으며,
  * 개발 모드에서 이름당 한 번 경고를 남깁니다. URL·에셋 경로도 `null` 입니다.
  *
+ * **`.svg` 경로는 파일 이름으로 lucide 를 먼저 찾는다** — `'/images/brand/check.svg'` 는 `'check'` 로 읽혀 lucide 체크가
+ * 그려진다(파일을 받지 않음). 목록에 그 이름이 없을 때만 Icon 이 파일을 받는다. 옛 브랜드 SVG 경로를 넘기던 화면과 모양을
+ * 맞추려고 **일부러 두는 동작**이다(2026-09-15 결정: 유지). 파일 그림 그대로가 필요하면 lucide 에 없는 파일 이름을 쓴다.
+ *
  * @example
  * const HomeIcon = useLucideIcon('home')
  * return HomeIcon ? <HomeIcon size={20} /> : null

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

@@ -0,0 +1,9 @@
+/**
+ * @internal 누름 처리기가 **약속(Promise)을 돌려주면 끝날 때까지 다시 누르지 못하게** 잠근다.
+ * ErrorState 의 onRetry·EmptyState 의 action.onClick 이 쓴다 — 느린 다시 불러오기에서 두 번 눌러 요청이 두 번 나갔다.
+ * 약속이 아니면 지금처럼 매번 부른다. 실패(reject)해도 풀린다. 공개 export 아님.
+ */
+export declare function usePendingPress(fn?: () => unknown): {
+    pending: boolean;
+    press: () => void;
+};

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

@@ -0,0 +1,26 @@
+'use client';
+import { useCallback, useEffect, useRef, useState } from 'react';
+/**
+ * @internal 누름 처리기가 **약속(Promise)을 돌려주면 끝날 때까지 다시 누르지 못하게** 잠근다.
+ * ErrorState 의 onRetry·EmptyState 의 action.onClick 이 쓴다 — 느린 다시 불러오기에서 두 번 눌러 요청이 두 번 나갔다.
+ * 약속이 아니면 지금처럼 매번 부른다. 실패(reject)해도 풀린다. 공개 export 아님.
+ */
+export function usePendingPress(fn) {
+    const [pending, setPending] = useState(false);
+    const 진행중 = useRef(false);
+    const 붙어있음 = useRef(true);
+    useEffect(() => { 붙어있음.current = true; return () => { 붙어있음.current = false; }; }, []);
+    const press = useCallback(() => {
+        if (!fn || 진행중.current)
+            return;
+        const r = fn();
+        if (r && typeof r.then === 'function') {
+            진행중.current = true;
+            setPending(true);
+            const 풀기 = () => { 진행중.current = false; if (붙어있음.current)
+                setPending(false); };
+            r.then(풀기, 풀기);
+        }
+    }, [fn]);
+    return { pending, press };
+}

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

@@ -0,0 +1,15 @@
+/** OS '동작 줄이기'(prefers-reduced-motion: reduce) 미디어 쿼리 */
+export declare const REDUCED_MOTION_QUERY = "(prefers-reduced-motion: reduce)";
+/**
+ * 지금 '동작 줄이기' 가 켜져 있는가 — 부르는 순간의 값(콜백 안에서 타이머 길이를 정할 때).
+ * `matchMedia` 가 없는 환경(서버·오래된 시험 환경)에서는 false.
+ */
+export declare function prefersReducedMotion(): boolean;
+/**
+ * '동작 줄이기' 설정을 따라가는 훅(바뀌면 다시 그린다).
+ *
+ * CSS 의 전역 규칙(styles.css)은 animation·transition 을 0 으로 줄이지만, **JS 가 기다리는 닫기 대기**
+ * (Popup 260ms·Tooltip 200ms·TrainingPagePopup 160ms)는 못 줄인다 — 움직임은 없는데 창이 그만큼 늦게 사라지고
+ * 그동안 투명한 막이 누름을 가로챘다. 그 대기를 이 값으로 0 으로 만든다.
+ */
+export declare function usePrefersReducedMotion(): boolean;

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

@@ -0,0 +1,26 @@
+'use client';
+import useMediaQuery from './useMediaQuery';
+/** OS '동작 줄이기'(prefers-reduced-motion: reduce) 미디어 쿼리 */
+export const REDUCED_MOTION_QUERY = '(prefers-reduced-motion: reduce)';
+/**
+ * 지금 '동작 줄이기' 가 켜져 있는가 — 부르는 순간의 값(콜백 안에서 타이머 길이를 정할 때).
+ * `matchMedia` 가 없는 환경(서버·오래된 시험 환경)에서는 false.
+ */
+export function prefersReducedMotion() {
+    try {
+        return typeof window !== 'undefined' && typeof window.matchMedia === 'function' && window.matchMedia(REDUCED_MOTION_QUERY).matches;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * '동작 줄이기' 설정을 따라가는 훅(바뀌면 다시 그린다).
+ *
+ * CSS 의 전역 규칙(styles.css)은 animation·transition 을 0 으로 줄이지만, **JS 가 기다리는 닫기 대기**
+ * (Popup 260ms·Tooltip 200ms·TrainingPagePopup 160ms)는 못 줄인다 — 움직임은 없는데 창이 그만큼 늦게 사라지고
+ * 그동안 투명한 막이 누름을 가로챘다. 그 대기를 이 값으로 0 으로 만든다.
+ */
+export function usePrefersReducedMotion() {
+    return useMediaQuery(REDUCED_MOTION_QUERY);
+}

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

@@ -42,8 +42,32 @@ export declare function useTablePaging<T>(rows: readonly T[], resetOn?: unknown,
     };
     setPage: import("react").Dispatch<import("react").SetStateAction<number>>;
 };
-/** 머리행 정렬 상태 — 같은 칸을 다시 누르면 방향이 뒤집힌다 @public */
-export declare function useTableSort<K extends string>(): {
+/** `useTableSort` 의 선택 인자. @public */
+export interface TableSortOptions<K extends string> {
+    /** 머리를 눌러 정렬이 바뀔 때 바뀐 정렬로 불린다 — 쪽을 따로 들고 있는 표가 첫 쪽으로 돌아가는 자리 등. */
+    onSortChange?: (sort: {
+        key: K;
+        asc: boolean;
+    }) => void;
+}
+/**
+ * 머리행 정렬 상태 — 같은 칸을 다시 누르면 방향이 뒤집힌다.
+ *
+ * **정렬이 바뀌면 첫 쪽으로** — `useTablePaging` 의 `resetOn` 에 돌려받은 `정렬` 을 그대로 넣는다.
+ * `정렬` 은 누를 때만 새 객체가 되므로(렌더마다 새로 만들지 않는다) 그 자체가 열쇠다. 쪽을 따로 들고 있으면 `onSortChange` 에서 되돌린다.
+ *
+ * `sortRows(rows, 값)` 은 지금 정렬로 줄을 세운 **새 배열**을 준다(정렬이 없으면 받은 배열 그대로) — `칸순`(숫자는 수로,
+ * 한글·영문은 사람 차례) 으로 견주고 **빈 값(null·undefined·'')은 오름·내림 모두 맨 뒤**(ListPopup 과 같은 규칙).
+ *
+ * @example
+ * const { 정렬, 칸, sortRows } = useTableSort<'name' | 'joined'>()
+ * const 세운줄 = useMemo(() => sortRows(rows, (r, key) => r[key]), [rows, sortRows])
+ * const { pageRows, pageSizeProps, paginationProps } = useTablePaging(세운줄, 정렬)   // 정렬이 바뀌면 첫 쪽
+ * <Table fields={[칸('이름', 'name'), 칸('가입일', 'joined')]} … />
+ *
+ * @public
+ */
+export declare function useTableSort<K extends string>(opts?: TableSortOptions<K>): {
     정렬: {
         key: K;
         asc: boolean;
@@ -53,4 +77,5 @@ export declare function useTableSort<K extends string>(): {
         sortDir: "desc" | "asc" | null;
         onClick: () => void;
     };
+    sortRows: <R>(rows: readonly R[], 값: (row: R, key: K) => unknown) => readonly R[];
 };