@ihabdevteam/core 0.171.0 → 0.173.0

package/dist/ihabdevteam-core.d.ts

@@ -1556,7 +1556,7 @@ export declare function copyText(text: string): Promise<boolean>;
  *
  * 값은 손으로 적고 `test/coreVersion.test.ts` 가 package.json 과 어긋나면 운다.
  */
-export declare const CORE_VERSION = "0.171.0";
+export declare const CORE_VERSION = "0.173.0";
 
 /** @public */
 declare const coreDefault: Record<string, unknown>;
@@ -2869,6 +2869,9 @@ export declare function isThisWeekPick({ rank, voteCount, quota }: {
 /** @public */
 export declare function isTrainingDataLoaded(): boolean;
 
+/** 연락처가 `formatPhone` 이 끝까지 채워 낸 모양인가 — 규칙은 `PHONE_REGEX`. @public */
+export declare function isValidPhone(phone: string): boolean;
+
 /** @public 단어가 해당 타입의 문제(정답) 단어로 구조적으로 유효한가. 제약 없는 타입은 항상 true. */
 export declare function isValidQuestionWord(typeKey: WordTrainingTypeKey, word: string): boolean;
 
@@ -4167,6 +4170,25 @@ export declare interface PersonCardProps {
     className?: string;
 }
 
+/**
+ * 연락처가 **`formatPhone` 이 끝까지 채워 낸 모양** 인가.
+ *
+ * 만드는 쪽(`formatPhone`)은 코어인데 받는 쪽(형식 검사)은 소비자마다 한 벌씩 두고 있었다 —
+ * 말귀 회원앱·어드민에 같은 정규식이 한 벌씩 있었고, 둘이 같은지는 짝 시험이 지켰지만
+ * **코어가 만든 모양과 맞는지는 아무도 안 쟀다.** 실제로 코어가 050X·0303(앞자리 네 자리)을
+ * 받았을 때 그 두 벌도 손으로 함께 고쳐야 했다. 그래서 짝을 여기 둔다 — 아래 시험이
+ * "formatPhone 이 끝까지 채운 값은 늘 통과한다" 를 못 박는다.
+ *
+ * `formatPhone` 은 **덜 채운 입력을 그대로 돌려준다**(`010-12`). 그래서 빈값 검사만으로는
+ * 모자라고, 이 함수가 그 자리를 맡는다.
+ *
+ * 받는 꼴 — 휴대폰·지역번호(02·0NN)·050X 안심번호·0303 착신전환·**1588 등 대표번호**.
+ * 대표번호는 `formatPhone` 이 `1588-1234` 로 만들어 내므로 여기서도 받는다
+ * (0 으로 시작하는 것만 받던 소비자 정규식은 그 번호를 거절했다 — 코어가 만든 모양을 코어가 거절하는 꼴).
+ * @public
+ */
+export declare const PHONE_REGEX: RegExp;
+
 /**
  * 훈련할 음절(초성/모음/종성)을 고르는 FilterPanel 셸(shell) — 섹션 자체는 훈련 타입별 조건(caps)에
  * 따라 호출부(useWordTrainingFilter)가 구성해 넘긴다. WordTrainingFilterPanels의 [훈련 음절] 패널이 원 출처.
@@ -5904,7 +5926,6 @@ export declare type ShuffledItem = {
 
 declare type Side = '좌' | '우';
 
-/** @public */
 export declare function SideNav(props: SideNavProps): React_2.JSX.Element;
 
 /** @public */
@@ -5935,6 +5956,14 @@ export declare interface SideNavProps {
     appMode?: 'malgwi' | 'manager';
     /** 앱 모드 전환 콜백 */
     onAppModeChange?: (mode: 'malgwi' | 'manager') => void;
+    /**
+     * 갈래를 고를 때 **맨 위로 되돌릴 본문 스크롤 통** — CSS 고르개나 ref.
+     *
+     * 안 주면 `.content-area` 를 찾고(코어가 **소비자 클래스 이름을 붙잡고 있던 자리** 다 — 말귀가 그 이름을 바꾸는 날
+     * 화면은 멀쩡한데 내비를 눌러도 스크롤이 안 돌아갔다), 그것도 없으면 창을 굴린다.
+     * 본문이 `body` 가 아니라 제 통에서 구르는 셸(body 가 `overflow: hidden`)이면 **반드시 준다** — 창 굴리기는 그 앱에서 아무 일도 하지 않는다.
+     */
+    scrollContainer?: string | RefObject<HTMLElement | null>;
 }
 
 /**

package/dist/packages/core/src/components/SideNav.d.ts

@@ -1,5 +1,5 @@
 import './SideNav.css';
-import React, { type ReactNode } from 'react';
+import React, { type ReactNode, type RefObject } from 'react';
 /** @public */
 export interface SideNavItem {
     key?: string;
@@ -27,6 +27,13 @@ export interface SideNavProps {
     appMode?: 'malgwi' | 'manager';
     /** 앱 모드 전환 콜백 */
     onAppModeChange?: (mode: 'malgwi' | 'manager') => void;
+    /**
+     * 갈래를 고를 때 **맨 위로 되돌릴 본문 스크롤 통** — CSS 고르개나 ref.
+     *
+     * 안 주면 `.content-area` 를 찾고(코어가 **소비자 클래스 이름을 붙잡고 있던 자리** 다 — 말귀가 그 이름을 바꾸는 날
+     * 화면은 멀쩡한데 내비를 눌러도 스크롤이 안 돌아갔다), 그것도 없으면 창을 굴린다.
+     * 본문이 `body` 가 아니라 제 통에서 구르는 셸(body 가 `overflow: hidden`)이면 **반드시 준다** — 창 굴리기는 그 앱에서 아무 일도 하지 않는다.
+     */
+    scrollContainer?: string | RefObject<HTMLElement | null>;
 }
-/** @public */
 export default function SideNav(props: SideNavProps): React.JSX.Element;

package/dist/packages/core/src/components/SideNav.js

@@ -7,6 +7,7 @@ import Badge from './Badge';
 import React, { useCallback } from 'react';
 import { useTranslation } from 'react-i18next';
 import { isSafeOpenHref } from '../utils/safeHref';
+import { devWarnOnce } from '../utils/devWarn';
 /** 단추 이름에 개수를 붙인다 — 뱃지는 aria-hidden 이라 개수는 이름으로만 전해진다(BottomNav 와 같은 문구). */
 function nameWithCount(t, label, count) {
     return count && count > 0 ? t('nav.badgeLabel', { label, count, defaultValue: '{{label}}, {{count}}개' }) : label;
@@ -55,9 +56,33 @@ function SideNavButton(props) {
     return (_jsxs("button", { type: "button", className: btnClass, onClick: handleClick, "aria-label": typeof text === 'string' ? nameWithCount(t, text, badgeCount) : undefined, "aria-current": active ? 'page' : undefined, style: style, "aria-disabled": isDisabled, children: [iconElement, _jsx("span", { className: `side-nav__label button-1 f`, style: labelStyle, children: text }), badgeCount > 0 && (_jsx(Badge, { type: "dot", position: "inline", number: Math.min(badgeCount, 99), size: 24, "aria-hidden": true })), state === 'loading' && (_jsx("span", { className: "side-nav__spinner", role: "img", "aria-label": t('loader.loading', '불러오는 중…') }))] }));
 }
 /** @public */
+/** 기본 고르개 — 소비자가 `scrollContainer` 를 안 줄 때 찾아 보는 이름(옛 동작 유지). @internal */
+const 기본통고르개 = '.content-area';
+/**
+ * 갈래를 고른 뒤 본문을 맨 위로. 통을 못 찾으면 창을 굴리는데, 본문이 제 통에서 구르는 셸에서는
+ * 그것이 **아무 일도 하지 않는다** — 그때는 조용히 죽는 대신 개발 모드에 한 번 알린다.
+ */
+function 맨위로(scrollContainer) {
+    try {
+        const el = typeof scrollContainer === 'string'
+            ? document.querySelector(scrollContainer)
+            : scrollContainer?.current ?? document.querySelector(기본통고르개);
+        if (el) {
+            el.scrollTop = 0;
+            return;
+        }
+        const 문서 = document.scrollingElement ?? document.documentElement;
+        /* 창도 구를 수 없으면(본문이 다른 통에서 구른다) 이 기능은 조용히 죽는다 — 그 사실을 알린다 */
+        if (문서 && 문서.scrollHeight <= 문서.clientHeight) {
+            devWarnOnce('side-nav-scroll-container', `[SideNav] 본문을 맨 위로 되돌릴 통을 못 찾았다(기본 ${기본통고르개}) — 창도 구를 수 없어 아무 일도 하지 않는다. scrollContainer 로 통을 알려 준다.`);
+        }
+        window.scrollTo({ top: 0 });
+    }
+    catch (_) { }
+}
 export default function SideNav(props) {
     const { t } = useTranslation();
-    const { items = [], activeKey, onChange, unreadCount, onDebug, onNotification, onAccount, onSetting, onHelp, appMode, onAppModeChange } = props || {};
+    const { items = [], activeKey, onChange, unreadCount, onDebug, onNotification, onAccount, onSetting, onHelp, appMode, onAppModeChange, scrollContainer } = props || {};
     /* 모드를 안 주면 말귀로 본다 — Header(브랜드)·BottomNav 와 같게. 전에는 여기만 매니저로 봐 같은 화면에서
        데스크톱은 '말귀로 이동', 모바일은 '말귀 매니저' 로 서로 반대를 가리켰다. */
     const isManager = appMode === 'manager';
@@ -80,14 +105,7 @@ export default function SideNav(props) {
                                         return;
                                     }
                                     onChange?.(it.key);
-                                    try {
-                                        const contentEl = document.querySelector('.content-area');
-                                        if (contentEl)
-                                            contentEl.scrollTop = 0;
-                                        else
-                                            window.scrollTo({ top: 0 });
-                                    }
-                                    catch (_) { }
+                                    맨위로(scrollContainer);
                                     /* 키보드로 고르면 포커스가 레일 안에 남으므로 태블릿 레일도 펼친 채 둔다(:focus-within) —
                                        아래 강제 접힘은 마우스가 들어와야 풀리므로 키보드 사용자에게 걸면 레일이 닫힌 채 포커스만 남는다. */
                                     if (!fromPointer)

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

@@ -3,6 +3,26 @@
  * 입력에 대시가 있든 없든, 어떤 포맷이든 처리.
  */
 export declare function formatPhone(raw: string): string;
+/**
+ * 연락처가 **`formatPhone` 이 끝까지 채워 낸 모양** 인가.
+ *
+ * 만드는 쪽(`formatPhone`)은 코어인데 받는 쪽(형식 검사)은 소비자마다 한 벌씩 두고 있었다 —
+ * 말귀 회원앱·어드민에 같은 정규식이 한 벌씩 있었고, 둘이 같은지는 짝 시험이 지켰지만
+ * **코어가 만든 모양과 맞는지는 아무도 안 쟀다.** 실제로 코어가 050X·0303(앞자리 네 자리)을
+ * 받았을 때 그 두 벌도 손으로 함께 고쳐야 했다. 그래서 짝을 여기 둔다 — 아래 시험이
+ * "formatPhone 이 끝까지 채운 값은 늘 통과한다" 를 못 박는다.
+ *
+ * `formatPhone` 은 **덜 채운 입력을 그대로 돌려준다**(`010-12`). 그래서 빈값 검사만으로는
+ * 모자라고, 이 함수가 그 자리를 맡는다.
+ *
+ * 받는 꼴 — 휴대폰·지역번호(02·0NN)·050X 안심번호·0303 착신전환·**1588 등 대표번호**.
+ * 대표번호는 `formatPhone` 이 `1588-1234` 로 만들어 내므로 여기서도 받는다
+ * (0 으로 시작하는 것만 받던 소비자 정규식은 그 번호를 거절했다 — 코어가 만든 모양을 코어가 거절하는 꼴).
+ * @public
+ */
+export declare const PHONE_REGEX: RegExp;
+/** 연락처가 `formatPhone` 이 끝까지 채워 낸 모양인가 — 규칙은 `PHONE_REGEX`. @public */
+export declare function isValidPhone(phone: string): boolean;
 /**
  * 날짜를 앱 표준 형식 YYYY.MM.DD 로 정규화.
  * 지원 입력: YYYYMMDD / YYYY-MM-DD / YYYY.MM.DD / ISO datetime 문자열

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

@@ -46,6 +46,28 @@ export function formatPhone(raw) {
     // 끝 4자리를 먼저 고정하고 중간 그룹을 나머지 길이로 계산한다.
     return `${d.slice(0, 3)}-${d.slice(3, d.length - 4)}-${d.slice(d.length - 4)}`;
 }
+/**
+ * 연락처가 **`formatPhone` 이 끝까지 채워 낸 모양** 인가.
+ *
+ * 만드는 쪽(`formatPhone`)은 코어인데 받는 쪽(형식 검사)은 소비자마다 한 벌씩 두고 있었다 —
+ * 말귀 회원앱·어드민에 같은 정규식이 한 벌씩 있었고, 둘이 같은지는 짝 시험이 지켰지만
+ * **코어가 만든 모양과 맞는지는 아무도 안 쟀다.** 실제로 코어가 050X·0303(앞자리 네 자리)을
+ * 받았을 때 그 두 벌도 손으로 함께 고쳐야 했다. 그래서 짝을 여기 둔다 — 아래 시험이
+ * "formatPhone 이 끝까지 채운 값은 늘 통과한다" 를 못 박는다.
+ *
+ * `formatPhone` 은 **덜 채운 입력을 그대로 돌려준다**(`010-12`). 그래서 빈값 검사만으로는
+ * 모자라고, 이 함수가 그 자리를 맡는다.
+ *
+ * 받는 꼴 — 휴대폰·지역번호(02·0NN)·050X 안심번호·0303 착신전환·**1588 등 대표번호**.
+ * 대표번호는 `formatPhone` 이 `1588-1234` 로 만들어 내므로 여기서도 받는다
+ * (0 으로 시작하는 것만 받던 소비자 정규식은 그 번호를 거절했다 — 코어가 만든 모양을 코어가 거절하는 꼴).
+ * @public
+ */
+export const PHONE_REGEX = /^(?:(?:0\d{1,2}|050\d|0303)-\d{3,4}-\d{4}|1[5-9]\d{2}-\d{4})$/;
+/** 연락처가 `formatPhone` 이 끝까지 채워 낸 모양인가 — 규칙은 `PHONE_REGEX`. @public */
+export function isValidPhone(phone) {
+    return PHONE_REGEX.test(phone);
+}
 /**
  * 날짜를 앱 표준 형식 YYYY.MM.DD 로 정규화.
  * 지원 입력: YYYYMMDD / YYYY-MM-DD / YYYY.MM.DD / ISO datetime 문자열

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

@@ -36,7 +36,7 @@ export { createTTSUrlResolver } from './utils/ttsResolver';
 export type { CreateTTSResolverOptions } from './utils/ttsResolver';
 export { toStorageName, toBase64UrlSafe, officialSoundPath } from './utils/encoding';
 export { copyText } from './utils/clipboard';
-export { formatPhone, normalizeDate, dateToDb, formatTimeHM, formatCount } from './utils/format';
+export { formatPhone, PHONE_REGEX, isValidPhone, normalizeDate, dateToDb, formatTimeHM, formatCount } from './utils/format';
 export { configureTrainingCategories, getTopicTypes, getTrainingTypes } from './utils/categories';
 export type { TopicType, TopicSubType, TrainingType, TrainingCategoryConfig } from './utils/categories';
 export { formatYmd, formatRelativeTime, getTodayKst, getTodayKstDate, kstStartOfDay, parseLocalYmd, toKstYmd, toKstHm, formatDateKo, formatDateLongKo, formatDatetimeKo, formatDateLocale, formatDateLongLocale } from './utils/date';

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

@@ -25,7 +25,7 @@ export { configureNoiseSettingsStore, loadNoiseSettings, saveNoiseSettings, repo
 export { createTTSUrlResolver } from './utils/ttsResolver';
 export { toStorageName, toBase64UrlSafe, officialSoundPath } from './utils/encoding';
 export { copyText } from './utils/clipboard';
-export { formatPhone, normalizeDate, dateToDb, formatTimeHM, formatCount } from './utils/format';
+export { formatPhone, PHONE_REGEX, isValidPhone, normalizeDate, dateToDb, formatTimeHM, formatCount } from './utils/format';
 export { configureTrainingCategories, getTopicTypes, getTrainingTypes } from './utils/categories';
 export { formatYmd, formatRelativeTime, getTodayKst, getTodayKstDate, kstStartOfDay, parseLocalYmd, toKstYmd, toKstHm, formatDateKo, formatDateLongKo, formatDatetimeKo, formatDateLocale, formatDateLongLocale } from './utils/date';
 export { getSavedTheme, applyTheme, initTheme } from './utils/theme';

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

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

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

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