@ihabdevteam/core 0.192.0 → 0.194.0

package/dist/ihabdevteam-core.d.ts

@@ -1430,7 +1430,16 @@ export declare interface ConfirmPopupProps {
     title: ReactNode;
     /** 본문 메시지 */
     message: ReactNode;
-    /** details/message 위(본문 최상단)에 놓을 콘텐츠 — 미리보기 카드 등. 가운데 정렬. */
+    /**
+     * details·message 위(본문 최상단)에 놓을 것 — 미리보기 카드·표 등.
+     *
+     * **여럿을 주면 세로로 쌓인다**(가로는 가운데, 사이는 `--spacing-m`). 예전에는 가로 줄이라
+     * 둘을 넣으면 나란히 섰고, 그래서 부르는 쪽마다 세로 통을 하나씩 더 두르고 있었다(0.193.0 에
+     * 여기로). 제 폭을 정한 것(`width: 100%` 인 표 틀·입력칸)은 그대로 꽉 찬다.
+     *
+     * 이 자리를 주면 **확인창의 더해 둔 위 여백도 되돌린다** — 글만 있는 확인창에서는 그 한 뼘이
+     * 숨 쉴 자리지만, 맨 위에 표나 카드가 서면 제목과 내용을 공연히 벌려 놓는다.
+     */
     topContent?: ReactNode;
     /**
      * 결정에 필요한 정보를 표(header 없는 Panel)로 message 위에 보여줄 때 사용.
@@ -1617,7 +1626,7 @@ export declare function copyText(text: string): Promise<boolean>;
  *
  * 값은 손으로 적고 `test/coreVersion.test.ts` 가 package.json 과 어긋나면 운다.
  */
-export declare const CORE_VERSION = "0.192.0";
+export declare const CORE_VERSION = "0.194.0";
 
 /** @public */
 declare const coreDefault: Record<string, unknown>;
@@ -4880,6 +4889,35 @@ export declare interface PopupProps {
 
 export declare const POS_LABEL: Record<string, string>;
 
+/**
+ * **늦게 받는 화면 청크를 한가할 때 미리 받아 둔다.**
+ *
+ * `lazyPage` 로 미룬 화면은 **그리려는 순간** 청크를 받는다. 그 사이 화면에는 동그라미만 돌고
+ * 제목도 구획도 하나도 없다(말귀 실측 2026-09-20: 고객 상세가 누른 뒤 **364ms** 동안 빈 화면.
+ * 사용자가 짚었다 — "고객을 누르면 pagetitle, 차트섹션들이 하나도 안 보이는 순간이 있는데").
+ *
+ * 그래서 **누르기 전에** 받아 둔다. 목록이 선 뒤 한가할 때 같은 모듈을 한 번 부르면 번들러가
+ * 캐시하고, 누르는 순간 `lazy` 가 곧바로 풀려 **뼈대가 먼저 선다** — 자료를 기다리는 일은 그
+ * 뼈대 안에서 일어난다.
+ *
+ * 지키는 것 둘:
+ * - **첫 그리기를 안 건드린다.** 화면이 선 뒤 한가한 틈에만 받는다(`requestIdleCallback`).
+ *   그 함수는 **사파리에 없다** — 없으면 짧게 미뤄(300ms) 그리는 일을 막지 않을 만큼만 늦춘다.
+ * - **실패를 삼킨다.** 미리 받기가 안 되면 누를 때 받으면 된다(그러면 예전과 같을 뿐이다).
+ *   그것 때문에 오류 화면을 띄울 일이 아니다.
+ *
+ * 돌려주는 것은 **그만두는 함수**다 — 효과에서 그대로 돌려주면 화면을 떠날 때 예약이 걷힌다.
+ *
+ * ```ts
+ * useEffect(() => prefetchChunk(() => import('./pages/CustomerDetail')), [])
+ * ```
+ *
+ * 두 앱(회원앱 · 어드민)이 한 벌씩 들고 있던 것이다 — 번들이 갈려 앱끼리는 합칠 수 없는
+ * 자리라 코어로 왔다(2026-09-25). 브라우저 차이를 아는 일은 `chunkSkew`·`lazyPage` 와 같은 결이다.
+ * @public
+ */
+export declare function prefetchChunk(...loads: readonly (() => Promise<unknown>)[]): () => void;
+
 /**
  * @public
  * 여러 단어의 이미지 존재 여부를 사전 확인 (병렬). localStorage에 영구 저장됨.
@@ -9029,6 +9067,29 @@ export declare function usePagedList<T>(items: T[], perPage: number, page: numbe
     curPage: number;
 };
 
+/**
+ * **거르는 조건이 바뀌면 첫 쪽으로 돌아간다.** `usePagedList` 의 짝이다.
+ *
+ * 안 돌리면 **3쪽을 보던 채로 검색어를 바꿨을 때 결과가 한 쪽뿐이라 빈 표가 뜬다** — 찾는 것이
+ * 없어서가 아니라 **없는 쪽을 보고 있어서**다. 화면 셋(어드민 문장·낱말 자료, 회원앱 낱말 관리)이
+ * 같은 세 줄을 각자 적고 있었고, 그것을 한 벌로 모은 뒤에도 두 앱에 한 벌씩 남아 있었다
+ * (번들이 갈려 앱끼리는 합칠 수 없는 자리다 — 2026-09-25 코어로).
+ *
+ * **효과(`useEffect`)가 아니라 렌더 중에 고친다.** 효과로 미루면 한 번은 옛 쪽 번호로 그려진 뒤
+ * 다음 프레임에 1쪽이 되어, 새 조건의 결과가 **빈 표로 한 번 깜빡인다.** 렌더 중 상태 조정은
+ * React 가 이 꼴을 위해 내준 길이다(같은 컴포넌트를 바로 다시 그린다).
+ *
+ * ```ts
+ * usePageResetOnChange(`${검색어}|${갈래}|${정렬}`, setPage)
+ * const { pageItems, totalPages } = usePagedList(걸러낸것, 쪽크기, page)
+ * ```
+ *
+ * @param 열쇠 조건을 하나로 이어 붙인 글 — 이것이 달라지면 첫 쪽이다
+ * @param setPage 쪽 번호를 쥔 쪽에서 준다
+ * @public
+ */
+export declare function usePageResetOnChange(열쇠: string, setPage: (n: number) => void): void;
+
 /**
  * 비밀번호 변경 폼 상태와 핸들러를 캡슐화한 훅.
  * showModal 상태는 컴포넌트가 직접 관리 (훅 밖에 두어야 모달 열기 트리거 제어 가능).

package/dist/packages/core/src/components/Popup/ConfirmPopup.d.ts

@@ -6,7 +6,16 @@ export interface ConfirmPopupProps {
     title: ReactNode;
     /** 본문 메시지 */
     message: ReactNode;
-    /** details/message 위(본문 최상단)에 놓을 콘텐츠 — 미리보기 카드 등. 가운데 정렬. */
+    /**
+     * details·message 위(본문 최상단)에 놓을 것 — 미리보기 카드·표 등.
+     *
+     * **여럿을 주면 세로로 쌓인다**(가로는 가운데, 사이는 `--spacing-m`). 예전에는 가로 줄이라
+     * 둘을 넣으면 나란히 섰고, 그래서 부르는 쪽마다 세로 통을 하나씩 더 두르고 있었다(0.193.0 에
+     * 여기로). 제 폭을 정한 것(`width: 100%` 인 표 틀·입력칸)은 그대로 꽉 찬다.
+     *
+     * 이 자리를 주면 **확인창의 더해 둔 위 여백도 되돌린다** — 글만 있는 확인창에서는 그 한 뼘이
+     * 숨 쉴 자리지만, 맨 위에 표나 카드가 서면 제목과 내용을 공연히 벌려 놓는다.
+     */
     topContent?: ReactNode;
     /**
      * 결정에 필요한 정보를 표(header 없는 Panel)로 message 위에 보여줄 때 사용.

package/dist/packages/core/src/components/Popup/ConfirmPopup.js

@@ -74,7 +74,9 @@ export default function ConfirmPopup(props) {
         // onConfirm(서버 요청 등)이 진행 중일 때 X/ESC로 닫으면, 팝업은 즉시 사라지는데
         // 이미 시작된 요청은 계속 진행돼 완료 후 부모 state/토스트가 뒤늦게 갱신된다 —
         // 사용자는 "취소했다"고 믿었는데 실제로는 실행된 것처럼 보이는 문제를 막는다.
-        closeDisabled: busy, inline: inline, size: size, className: cx('confirm-popup', className), buttons: [
+        closeDisabled: busy, inline: inline, size: size, 
+        /* 위에 미리보기가 서면 더해 둔 위 여백을 되돌린다 — 까닭은 `Popup.css` 의 그 규칙에 */
+        className: cx('confirm-popup', topContent != null && 'confirm-popup--has-top', className), buttons: [
             ...(extraAction ? [{
                     label: extraAction.label,
                     variant: extraAction.variant ?? 'default',

package/dist/packages/core/src/components/Popup/Popup.css

@@ -202,7 +202,25 @@
 /* 확인 팝업은 본문 위/아래 여백을 20px씩 더(기본 20 → 40) */
 .confirm-popup .popup-content { padding-top: 40px; }
 .confirm-popup .popup-content__inner { padding-bottom: 40px; }
+/* **위에 미리보기가 서면 그 더한 여백은 되돌린다.** 글만 있는 확인창에서는 그 한 뼘이 숨 쉴
+   자리지만, 맨 위에 표나 카드가 서면 제목과 내용을 공연히 벌려 놓는다(사용자 지시 2026-09-23
+   "여백이 많아보여"). 부르는 쪽 둘이 각자 되돌리고 있던 것을 여기서 한다(2026-09-25). */
+.confirm-popup--has-top .popup-content { padding-top: var(--spacing-l); }
 /* details Panel과 아래 메시지 사이 간격 */
 .confirm-popup .panel + .confirm-popup__message { margin-top: 16px; }
-/* 최상단 미리보기(카드 등) — 가운데 정렬 + 아래 여백 */
-.confirm-popup__top { display: flex; justify-content: center; margin-bottom: 20px; }
+/* **최상단 자리 — 세로로 쌓고 가로는 가운데.**
+   예전에는 가로 줄(`justify-content: center`)이라, 이 자리에 둘을 넣으면 **나란히 섰다.**
+   그래서 둘 이상을 세워야 하는 창마다 세로 통을 하나씩 더 두르고 있었다(말귀 두 벌 — 표 저장
+   확인창·숙제 확인창. 두 파일이 "가로 가운데라 그냥 넣으면 나란히 선다" 는 말까지 따로 적어
+   두었다 — 그 말이 두 군데 있다는 것 자체가 여기 일이라는 신호였다, 2026-09-25).
+
+   하나만 넣던 자리는 그대로다: 가운데 맞춤(`align-items: center`)은 **제 폭을 안 정한 것**에만
+   걸리므로, `width: 100%` 를 가진 것(표 틀·입력칸)은 여전히 꽉 찬다. */
+.confirm-popup__top {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: var(--spacing-m);
+  margin-bottom: 20px;
+}
+.confirm-popup__top > * { max-width: 100%; }

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

@@ -0,0 +1,22 @@
+/**
+ * **거르는 조건이 바뀌면 첫 쪽으로 돌아간다.** `usePagedList` 의 짝이다.
+ *
+ * 안 돌리면 **3쪽을 보던 채로 검색어를 바꿨을 때 결과가 한 쪽뿐이라 빈 표가 뜬다** — 찾는 것이
+ * 없어서가 아니라 **없는 쪽을 보고 있어서**다. 화면 셋(어드민 문장·낱말 자료, 회원앱 낱말 관리)이
+ * 같은 세 줄을 각자 적고 있었고, 그것을 한 벌로 모은 뒤에도 두 앱에 한 벌씩 남아 있었다
+ * (번들이 갈려 앱끼리는 합칠 수 없는 자리다 — 2026-09-25 코어로).
+ *
+ * **효과(`useEffect`)가 아니라 렌더 중에 고친다.** 효과로 미루면 한 번은 옛 쪽 번호로 그려진 뒤
+ * 다음 프레임에 1쪽이 되어, 새 조건의 결과가 **빈 표로 한 번 깜빡인다.** 렌더 중 상태 조정은
+ * React 가 이 꼴을 위해 내준 길이다(같은 컴포넌트를 바로 다시 그린다).
+ *
+ * ```ts
+ * usePageResetOnChange(`${검색어}|${갈래}|${정렬}`, setPage)
+ * const { pageItems, totalPages } = usePagedList(걸러낸것, 쪽크기, page)
+ * ```
+ *
+ * @param 열쇠 조건을 하나로 이어 붙인 글 — 이것이 달라지면 첫 쪽이다
+ * @param setPage 쪽 번호를 쥔 쪽에서 준다
+ * @public
+ */
+export declare function usePageResetOnChange(열쇠: string, setPage: (n: number) => void): void;

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

@@ -0,0 +1,30 @@
+'use client';
+import { useState } from 'react';
+/**
+ * **거르는 조건이 바뀌면 첫 쪽으로 돌아간다.** `usePagedList` 의 짝이다.
+ *
+ * 안 돌리면 **3쪽을 보던 채로 검색어를 바꿨을 때 결과가 한 쪽뿐이라 빈 표가 뜬다** — 찾는 것이
+ * 없어서가 아니라 **없는 쪽을 보고 있어서**다. 화면 셋(어드민 문장·낱말 자료, 회원앱 낱말 관리)이
+ * 같은 세 줄을 각자 적고 있었고, 그것을 한 벌로 모은 뒤에도 두 앱에 한 벌씩 남아 있었다
+ * (번들이 갈려 앱끼리는 합칠 수 없는 자리다 — 2026-09-25 코어로).
+ *
+ * **효과(`useEffect`)가 아니라 렌더 중에 고친다.** 효과로 미루면 한 번은 옛 쪽 번호로 그려진 뒤
+ * 다음 프레임에 1쪽이 되어, 새 조건의 결과가 **빈 표로 한 번 깜빡인다.** 렌더 중 상태 조정은
+ * React 가 이 꼴을 위해 내준 길이다(같은 컴포넌트를 바로 다시 그린다).
+ *
+ * ```ts
+ * usePageResetOnChange(`${검색어}|${갈래}|${정렬}`, setPage)
+ * const { pageItems, totalPages } = usePagedList(걸러낸것, 쪽크기, page)
+ * ```
+ *
+ * @param 열쇠 조건을 하나로 이어 붙인 글 — 이것이 달라지면 첫 쪽이다
+ * @param setPage 쪽 번호를 쥔 쪽에서 준다
+ * @public
+ */
+export function usePageResetOnChange(열쇠, setPage) {
+    const [본열쇠, set본열쇠] = useState(열쇠);
+    if (본열쇠 !== 열쇠) {
+        set본열쇠(열쇠);
+        setPage(1);
+    }
+}

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

@@ -23,6 +23,7 @@ export * from './hooks/useEscToClose';
 export * from './hooks/useWordMeanings';
 export * from './hooks/useHoverAnchor';
 export * from './hooks/usePagedList';
+export * from './hooks/usePageResetOnChange';
 export * from './hooks/useToastState';
 export { useTrainingTypeLabels } from './hooks/useTrainingTypeLabels';
 export { CORE_VERSION } from './version';

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

@@ -22,6 +22,7 @@ export * from './hooks/useEscToClose';
 export * from './hooks/useWordMeanings';
 export * from './hooks/useHoverAnchor';
 export * from './hooks/usePagedList';
+export * from './hooks/usePageResetOnChange';
 // 토스트 상태(문구 + 종류 + 재실행 번호). 회원 앱의 useToast 가 이 위에 얹혀 있다 —
 // 같은 관용구를 두 벌로 두지 않으려면 패키지 밖에서도 보여야 한다.
 export * from './hooks/useToastState';

package/dist/packages/core/src/utils/prefetchChunk.d.ts

@@ -0,0 +1,28 @@
+/**
+ * **늦게 받는 화면 청크를 한가할 때 미리 받아 둔다.**
+ *
+ * `lazyPage` 로 미룬 화면은 **그리려는 순간** 청크를 받는다. 그 사이 화면에는 동그라미만 돌고
+ * 제목도 구획도 하나도 없다(말귀 실측 2026-09-20: 고객 상세가 누른 뒤 **364ms** 동안 빈 화면.
+ * 사용자가 짚었다 — "고객을 누르면 pagetitle, 차트섹션들이 하나도 안 보이는 순간이 있는데").
+ *
+ * 그래서 **누르기 전에** 받아 둔다. 목록이 선 뒤 한가할 때 같은 모듈을 한 번 부르면 번들러가
+ * 캐시하고, 누르는 순간 `lazy` 가 곧바로 풀려 **뼈대가 먼저 선다** — 자료를 기다리는 일은 그
+ * 뼈대 안에서 일어난다.
+ *
+ * 지키는 것 둘:
+ * - **첫 그리기를 안 건드린다.** 화면이 선 뒤 한가한 틈에만 받는다(`requestIdleCallback`).
+ *   그 함수는 **사파리에 없다** — 없으면 짧게 미뤄(300ms) 그리는 일을 막지 않을 만큼만 늦춘다.
+ * - **실패를 삼킨다.** 미리 받기가 안 되면 누를 때 받으면 된다(그러면 예전과 같을 뿐이다).
+ *   그것 때문에 오류 화면을 띄울 일이 아니다.
+ *
+ * 돌려주는 것은 **그만두는 함수**다 — 효과에서 그대로 돌려주면 화면을 떠날 때 예약이 걷힌다.
+ *
+ * ```ts
+ * useEffect(() => prefetchChunk(() => import('./pages/CustomerDetail')), [])
+ * ```
+ *
+ * 두 앱(회원앱 · 어드민)이 한 벌씩 들고 있던 것이다 — 번들이 갈려 앱끼리는 합칠 수 없는
+ * 자리라 코어로 왔다(2026-09-25). 브라우저 차이를 아는 일은 `chunkSkew`·`lazyPage` 와 같은 결이다.
+ * @public
+ */
+export declare function prefetchChunk(...loads: readonly (() => Promise<unknown>)[]): () => void;

package/dist/packages/core/src/utils/prefetchChunk.js

@@ -0,0 +1,44 @@
+/**
+ * **늦게 받는 화면 청크를 한가할 때 미리 받아 둔다.**
+ *
+ * `lazyPage` 로 미룬 화면은 **그리려는 순간** 청크를 받는다. 그 사이 화면에는 동그라미만 돌고
+ * 제목도 구획도 하나도 없다(말귀 실측 2026-09-20: 고객 상세가 누른 뒤 **364ms** 동안 빈 화면.
+ * 사용자가 짚었다 — "고객을 누르면 pagetitle, 차트섹션들이 하나도 안 보이는 순간이 있는데").
+ *
+ * 그래서 **누르기 전에** 받아 둔다. 목록이 선 뒤 한가할 때 같은 모듈을 한 번 부르면 번들러가
+ * 캐시하고, 누르는 순간 `lazy` 가 곧바로 풀려 **뼈대가 먼저 선다** — 자료를 기다리는 일은 그
+ * 뼈대 안에서 일어난다.
+ *
+ * 지키는 것 둘:
+ * - **첫 그리기를 안 건드린다.** 화면이 선 뒤 한가한 틈에만 받는다(`requestIdleCallback`).
+ *   그 함수는 **사파리에 없다** — 없으면 짧게 미뤄(300ms) 그리는 일을 막지 않을 만큼만 늦춘다.
+ * - **실패를 삼킨다.** 미리 받기가 안 되면 누를 때 받으면 된다(그러면 예전과 같을 뿐이다).
+ *   그것 때문에 오류 화면을 띄울 일이 아니다.
+ *
+ * 돌려주는 것은 **그만두는 함수**다 — 효과에서 그대로 돌려주면 화면을 떠날 때 예약이 걷힌다.
+ *
+ * ```ts
+ * useEffect(() => prefetchChunk(() => import('./pages/CustomerDetail')), [])
+ * ```
+ *
+ * 두 앱(회원앱 · 어드민)이 한 벌씩 들고 있던 것이다 — 번들이 갈려 앱끼리는 합칠 수 없는
+ * 자리라 코어로 왔다(2026-09-25). 브라우저 차이를 아는 일은 `chunkSkew`·`lazyPage` 와 같은 결이다.
+ * @public
+ */
+export function prefetchChunk(...loads) {
+    let 취소됨 = false;
+    const 받기 = () => { if (!취소됨)
+        for (const load of loads)
+            void load().catch(() => { }); };
+    const idle = globalThis.requestIdleCallback;
+    if (idle) {
+        const id = idle(받기, { timeout: 2000 });
+        return () => {
+            취소됨 = true;
+            const cancel = globalThis.cancelIdleCallback;
+            cancel?.(id);
+        };
+    }
+    const id = setTimeout(받기, 300);
+    return () => { 취소됨 = true; clearTimeout(id); };
+}

package/dist/packages/core/src/utils.d.ts

@@ -57,4 +57,5 @@ export { PLAN_FEATURES, PLAN_LIMITS, TIER_RANK, getPlanTier, isManagerTier, type
 export { WORD_SUGGESTION_WEEKLY_QUOTA, WORD_SUGGESTION_ACCOUNT_LIMIT, WORD_SUGGESTION_EXISTING_ERROR, isThisWeekPick, } from './utils/wordSuggestionPolicy';
 export { recoverFromSkew, skewReloadPending } from './utils/chunkSkew';
 export { lazyPage } from './utils/lazyPage';
+export { prefetchChunk } from './utils/prefetchChunk';
 export { CORE_VERSION } from './version';

package/dist/packages/core/src/utils.js

@@ -46,4 +46,5 @@ export { PLAN_FEATURES, PLAN_LIMITS, TIER_RANK, getPlanTier, isManagerTier, } fr
 export { WORD_SUGGESTION_WEEKLY_QUOTA, WORD_SUGGESTION_ACCOUNT_LIMIT, WORD_SUGGESTION_EXISTING_ERROR, isThisWeekPick, } from './utils/wordSuggestionPolicy';
 export { recoverFromSkew, skewReloadPending } from './utils/chunkSkew';
 export { lazyPage } from './utils/lazyPage';
+export { prefetchChunk } from './utils/prefetchChunk';
 export { CORE_VERSION } from './version';

package/dist/packages/core/src/version.d.ts

@@ -46,4 +46,4 @@
  *
  * 값은 손으로 적고 `test/coreVersion.test.ts` 가 package.json 과 어긋나면 운다.
  */
-export declare const CORE_VERSION = "0.192.0";
+export declare const CORE_VERSION = "0.194.0";

package/dist/packages/core/src/version.js

@@ -46,4 +46,4 @@
  *
  * 값은 손으로 적고 `test/coreVersion.test.ts` 가 package.json 과 어긋나면 운다.
  */
-export const CORE_VERSION = '0.192.0';
+export const CORE_VERSION = '0.194.0';