@ihabdevteam/core 0.193.0 → 0.194.0

package/dist/ihabdevteam-core.d.ts

@@ -1626,7 +1626,7 @@ export declare function copyText(text: string): Promise<boolean>;
  *
  * 값은 손으로 적고 `test/coreVersion.test.ts` 가 package.json 과 어긋나면 운다.
  */
-export declare const CORE_VERSION = "0.193.0";
+export declare const CORE_VERSION = "0.194.0";
 
 /** @public */
 declare const coreDefault: Record<string, unknown>;
@@ -4889,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에 영구 저장됨.
@@ -9038,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/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.193.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.193.0';
+export const CORE_VERSION = '0.194.0';