@ihabdevteam/core 0.172.0 → 0.174.0

package/dist/ihabdevteam-core.d.ts

@@ -543,7 +543,7 @@ export declare interface BoardProps<T> {
 }
 
 /** @public */
-export declare function BottomNav({ items, activeKey, onChange, appMode, onAppModeChange, moreItems, }: {
+export declare function BottomNav({ items, activeKey, onChange, appMode, onAppModeChange, moreItems, scrollContainer, }: {
     items?: NavItem[];
     activeKey?: string;
     onChange?: (key: string) => void;
@@ -551,6 +551,13 @@ export declare function BottomNav({ items, activeKey, onChange, appMode, onAppMo
     onAppModeChange?: (mode: 'malgwi' | 'manager') => void;
     /** nav 항목과 별개로 항상 더보기 메뉴에 노출되는 유틸(알림·설정·계정 등) */
     moreItems?: BottomNavMoreItem[];
+    /**
+     * 갈래를 고를 때 **맨 위로 되돌릴 본문 스크롤 통** — CSS 고르개나 ref. `SideNav` 와 같은 뜻이다.
+     *
+     * 모바일에서도 갈래를 바꾸면 본문이 위에서 시작해야 한다 — 전에는 데스크톱(SideNav)만 되돌려, 같은 앱에서
+     * 큰 화면은 위로 가고 작은 화면은 앞 화면의 스크롤 자리에 남았다. 유틸(더보기 메뉴의 알림·설정 등)은 갈래가 아니라 되돌리지 않는다.
+     */
+    scrollContainer?: string | RefObject<HTMLElement | null>;
 }): JSX.Element;
 
 /**
@@ -1556,7 +1563,7 @@ export declare function copyText(text: string): Promise<boolean>;
  *
  * 값은 손으로 적고 `test/coreVersion.test.ts` 가 package.json 과 어긋나면 운다.
  */
-export declare const CORE_VERSION = "0.172.0";
+export declare const CORE_VERSION = "0.174.0";
 
 /** @public */
 declare const coreDefault: Record<string, unknown>;
@@ -2682,7 +2689,7 @@ export declare function hasStructureContrast(A: Decomp, B: Decomp): boolean;
  *
  * @public
  */
-export declare function Header({ activeKey, onChange, items, malgwiItems: _malgwiItems, managerItems: _managerItems, unreadCount, onDebug, onNotification, onAccount, onSetting, onHelp, appMode, onAppModeChange }: {
+export declare function Header({ activeKey, onChange, items, malgwiItems: _malgwiItems, managerItems: _managerItems, unreadCount, onDebug, onNotification, onAccount, onSetting, onHelp, appMode, onAppModeChange, scrollContainer }: {
     activeKey?: string | null;
     onChange?: (key?: string) => void;
     /** 지금 모드의 내비 항목. 데스크톱은 SideNav, 모바일은 BottomNav 가 이 목록을 그린다. */
@@ -2702,6 +2709,13 @@ export declare function Header({ activeKey, onChange, items, malgwiItems: _malgw
     onHelp?: () => void;
     appMode?: 'malgwi' | 'manager';
     onAppModeChange?: (mode: 'malgwi' | 'manager') => void;
+    /**
+     * 갈래를 고를 때 **맨 위로 되돌릴 본문 스크롤 통** — CSS 고르개나 ref. 안쪽 `SideNav`·`BottomNav` 에 그대로 넘긴다.
+     *
+     * 본문이 `body` 가 아니라 제 통에서 구르는 셸(`body { overflow: hidden }`)이면 **반드시 준다** — 창 굴리기는 그 앱에서 아무 일도 하지 않는다.
+     * **ref 로 주는 것이 가장 낫다**: 고르개 글자로 주면 코어가 소비자 클래스 이름을 다시 붙잡는 꼴이고, ref 면 그 얽힘이 아예 없다.
+     */
+    scrollContainer?: string | RefObject<HTMLElement | null>;
 }): JSX.Element;
 
 /** @public */
@@ -5957,6 +5971,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/BottomNav.d.ts

@@ -1,3 +1,4 @@
+import { type RefObject } from 'react';
 import './BottomNav.css';
 import './Tooltip/Tooltip.css';
 /** @public */
@@ -27,7 +28,7 @@ export type BottomNavMoreItem = {
     onClick?: () => void;
 };
 /** @public */
-export default function BottomNav({ items, activeKey, onChange, appMode, onAppModeChange, moreItems, }: {
+export default function BottomNav({ items, activeKey, onChange, appMode, onAppModeChange, moreItems, scrollContainer, }: {
     items?: NavItem[];
     activeKey?: string;
     onChange?: (key: string) => void;
@@ -35,4 +36,11 @@ export default function BottomNav({ items, activeKey, onChange, appMode, onAppMo
     onAppModeChange?: (mode: 'malgwi' | 'manager') => void;
     /** nav 항목과 별개로 항상 더보기 메뉴에 노출되는 유틸(알림·설정·계정 등) */
     moreItems?: BottomNavMoreItem[];
+    /**
+     * 갈래를 고를 때 **맨 위로 되돌릴 본문 스크롤 통** — CSS 고르개나 ref. `SideNav` 와 같은 뜻이다.
+     *
+     * 모바일에서도 갈래를 바꾸면 본문이 위에서 시작해야 한다 — 전에는 데스크톱(SideNav)만 되돌려, 같은 앱에서
+     * 큰 화면은 위로 가고 작은 화면은 앞 화면의 스크롤 자리에 남았다. 유틸(더보기 메뉴의 알림·설정 등)은 갈래가 아니라 되돌리지 않는다.
+     */
+    scrollContainer?: string | RefObject<HTMLElement | null>;
 }): import("react").JSX.Element;

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

@@ -12,12 +12,13 @@ import MenuTooltip from './Tooltip/MenuTooltip';
 import './Tooltip/Tooltip.css';
 import { useAnchoredMenu, anchoredMenuZIndex } from '../hooks/useAnchoredMenu';
 import { useTranslation } from 'react-i18next';
+import { scrollNavTargetToTop } from '../utils/navScroll';
 const BTN_SIZE = 52;
 const BTN_GAP = 10;
 /** 배지 숫자 — SideNav·MenuTooltip 과 같이 99 에서 자른다. 0 이하·없음은 0. */
 const badgeOf = (n) => (n && n > 0 ? n : 0);
 /** @public */
-export default function BottomNav({ items = [], activeKey, onChange, appMode, onAppModeChange, moreItems = [], }) {
+export default function BottomNav({ items = [], activeKey, onChange, appMode, onAppModeChange, moreItems = [], scrollContainer, }) {
     const { t } = useTranslation();
     const nextMode = appMode === 'manager' ? 'malgwi' : 'manager';
     const modeIcon = appMode === 'manager' ? 'arrow-left' : 'arrow-right';
@@ -91,8 +92,10 @@ export default function BottomNav({ items = [], activeKey, onChange, appMode, on
                     onClick: () => {
                         if (it.state === 'disabled')
                             return;
-                        if (it.key && onChange)
+                        if (it.key && onChange) {
                             onChange(it.key);
+                            scrollNavTargetToTop(scrollContainer, 'BottomNav');
+                        }
                         handleCloseMore();
                     },
                 })),
@@ -115,6 +118,9 @@ export default function BottomNav({ items = [], activeKey, onChange, appMode, on
                     const count = badgeOf(it.badgeCount);
                     return (
                     // key 는 선택 prop 이다 — 없으면 자리 번호로(형제 key 가 모두 undefined 가 되던 것)
-                    _jsxs("span", { className: "bottom-nav__slot", children: [_jsx(Button, { htmlType: "button", size: 52, type: "dot", icon: it.icon, ariaLabel: nameWithCount(it.label, count), selected: !!it.key && it.key === activeKey, disabled: it.state === 'disabled', className: "bottom-nav-item", onClick: () => it.key && onChange?.(it.key) }), count > 0 && (_jsx("span", { "aria-hidden": "true", children: _jsx(Badge, { type: "dot", position: "top-right", number: Math.min(count, 99), size: 24 }) }))] }, it.key ?? `__slot-${i}`));
+                    _jsxs("span", { className: "bottom-nav__slot", children: [_jsx(Button, { htmlType: "button", size: 52, type: "dot", icon: it.icon, ariaLabel: nameWithCount(it.label, count), selected: !!it.key && it.key === activeKey, disabled: it.state === 'disabled', className: "bottom-nav-item", onClick: () => { if (it.key) {
+                                    onChange?.(it.key);
+                                    scrollNavTargetToTop(scrollContainer, 'BottomNav');
+                                } } }), count > 0 && (_jsx("span", { "aria-hidden": "true", children: _jsx(Badge, { type: "dot", position: "top-right", number: Math.min(count, 99), size: 24 }) }))] }, it.key ?? `__slot-${i}`));
                 }) }), showMore && (_jsxs(_Fragment, { children: [_jsx("div", { className: "bottom-nav__divider", "aria-hidden": "true" }), _jsx("div", { className: "bottom-nav__right", children: _jsxs("div", { ref: moreRef, className: "bottom-nav__slot", children: [_jsx(Button, { htmlType: "button", size: 52, type: "dot", icon: activeMore?.icon ?? 'ellipsis', ariaLabel: nameWithCount(activeMore?.label ?? t('nav.more', '더보기'), moreBadge), selected: !!activeMore, className: "bottom-nav-item", onClick: handleToggleMore, "aria-expanded": moreOpen, "aria-controls": moreOpen ? moreMenuId : undefined }), moreBadge > 0 && (_jsx("span", { "aria-hidden": "true", children: _jsx(Badge, { type: "dot", position: "top-right", number: Math.min(moreBadge, 99), size: 24 }) })), moreOpen && createPortal(_jsx("div", { id: moreMenuId, role: "group", "aria-label": t('nav.moreMenu', '더보기 메뉴'), className: "tooltip-content", style: menuStyle, ref: menuRef, children: _jsx(MenuTooltip, { columns: moreColumns, onClose: handleCloseMore }) }), document.body)] }) })] }))] }));
 }

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

@@ -1,3 +1,4 @@
+import { type RefObject } from 'react';
 import './Tooltip/Tooltip.css';
 import { type SideNavItem } from './SideNav';
 import './Header.css';
@@ -18,7 +19,7 @@ export declare function BrandIdentity({ appMode }: {
  *
  * @public
  */
-export default function Header({ activeKey, onChange, items, malgwiItems: _malgwiItems, managerItems: _managerItems, unreadCount, onDebug, onNotification, onAccount, onSetting, onHelp, appMode, onAppModeChange }: {
+export default function Header({ activeKey, onChange, items, malgwiItems: _malgwiItems, managerItems: _managerItems, unreadCount, onDebug, onNotification, onAccount, onSetting, onHelp, appMode, onAppModeChange, scrollContainer }: {
     activeKey?: string | null;
     onChange?: (key?: string) => void;
     /** 지금 모드의 내비 항목. 데스크톱은 SideNav, 모바일은 BottomNav 가 이 목록을 그린다. */
@@ -38,6 +39,13 @@ export default function Header({ activeKey, onChange, items, malgwiItems: _malgw
     onHelp?: () => void;
     appMode?: 'malgwi' | 'manager';
     onAppModeChange?: (mode: 'malgwi' | 'manager') => void;
+    /**
+     * 갈래를 고를 때 **맨 위로 되돌릴 본문 스크롤 통** — CSS 고르개나 ref. 안쪽 `SideNav`·`BottomNav` 에 그대로 넘긴다.
+     *
+     * 본문이 `body` 가 아니라 제 통에서 구르는 셸(`body { overflow: hidden }`)이면 **반드시 준다** — 창 굴리기는 그 앱에서 아무 일도 하지 않는다.
+     * **ref 로 주는 것이 가장 낫다**: 고르개 글자로 주면 코어가 소비자 클래스 이름을 다시 붙잡는 꼴이고, ref 면 그 얽힘이 아예 없다.
+     */
+    scrollContainer?: string | RefObject<HTMLElement | null>;
 }): import("react").JSX.Element;
 /**
  * `Header`의 alias입니다. 프로젝트 내 `Header`라는 이름이 이미 사용 중일 때 충돌 없이 임포트할 수 있습니다.

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

@@ -42,7 +42,7 @@ export function BrandIdentity({ appMode }) {
  *
  * @public
  */
-export default function Header({ activeKey, onChange, items, malgwiItems: _malgwiItems, managerItems: _managerItems, unreadCount, onDebug, onNotification, onAccount, onSetting, onHelp, appMode, onAppModeChange }) {
+export default function Header({ activeKey, onChange, items, malgwiItems: _malgwiItems, managerItems: _managerItems, unreadCount, onDebug, onNotification, onAccount, onSetting, onHelp, appMode, onAppModeChange, scrollContainer }) {
     const { t } = useTranslation();
     const isMobile = useMediaQuery("(max-width: 767px)");
     /* **모바일 하단 내비에 SideNav 항목을 옮겨 적는다.** 예전에는 `SideNavItem` 을 `NavItem` 으로
@@ -118,7 +118,7 @@ export default function Header({ activeKey, onChange, items, malgwiItems: _malgw
         }], [bottomMoreItems, activeKey, closeUtilMenu]);
     return (_jsxs("aside", { className: `header${appMode === 'manager' ? ' header--manager' : ''}`, children: [_jsxs("div", { className: "header__bi", children: [_jsx(BrandIdentity, { appMode: appMode }), _jsxs("div", { className: "header__menu-button", ref: utilTriggerRef, children: [_jsx(Button, { htmlType: "button", size: 48, type: "dot", shape: "pill", variant: "default", icon: 'menu', ariaLabel: onNotification && unreadCount && unreadCount > 0
                                     ? t('nav.badgeLabel', { label: t('header.menuOpen', '메뉴 열기'), count: unreadCount, defaultValue: '{{label}}, {{count}}개' })
-                                    : t('header.menuOpen', '메뉴 열기'), onClick: toggleUtilMenu, "aria-expanded": utilOpen, "aria-controls": utilOpen ? utilMenuId : undefined }), !!onNotification && !!unreadCount && unreadCount > 0 && (_jsx(Badge, { type: "dot", number: Math.min(unreadCount, 99), size: 24, "aria-hidden": true })), utilOpen && createPortal(_jsx("div", { id: utilMenuId, role: "group", "aria-label": t('header.utilMenu', '유틸리티 메뉴'), className: "tooltip-content", style: utilMenuStyle, ref: utilMenuRef, children: _jsx(MenuTooltip, { columns: utilColumns, onClose: closeUtilMenu }) }), document.body)] })] }), _jsx(SideNav, { items: items, activeKey: activeKey ?? undefined, onChange: onChange, unreadCount: unreadCount, onDebug: onDebug, onNotification: onNotification, onAccount: onAccount, onSetting: onSetting, onHelp: onHelp, appMode: appMode, onAppModeChange: onAppModeChange }), isMobile && _jsx(BottomNav, { items: bottomItems, activeKey: activeKey ?? undefined, onChange: handleBottomChange, appMode: appMode, onAppModeChange: onAppModeChange })] }));
+                                    : t('header.menuOpen', '메뉴 열기'), onClick: toggleUtilMenu, "aria-expanded": utilOpen, "aria-controls": utilOpen ? utilMenuId : undefined }), !!onNotification && !!unreadCount && unreadCount > 0 && (_jsx(Badge, { type: "dot", number: Math.min(unreadCount, 99), size: 24, "aria-hidden": true })), utilOpen && createPortal(_jsx("div", { id: utilMenuId, role: "group", "aria-label": t('header.utilMenu', '유틸리티 메뉴'), className: "tooltip-content", style: utilMenuStyle, ref: utilMenuRef, children: _jsx(MenuTooltip, { columns: utilColumns, onClose: closeUtilMenu }) }), document.body)] })] }), _jsx(SideNav, { scrollContainer: scrollContainer, items: items, activeKey: activeKey ?? undefined, onChange: onChange, unreadCount: unreadCount, onDebug: onDebug, onNotification: onNotification, onAccount: onAccount, onSetting: onSetting, onHelp: onHelp, appMode: appMode, onAppModeChange: onAppModeChange }), isMobile && _jsx(BottomNav, { items: bottomItems, activeKey: activeKey ?? undefined, onChange: handleBottomChange, scrollContainer: scrollContainer, appMode: appMode, onAppModeChange: onAppModeChange })] }));
 }
 /**
  * `Header`의 alias입니다. 프로젝트 내 `Header`라는 이름이 이미 사용 중일 때 충돌 없이 임포트할 수 있습니다.

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,14 @@ 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 { scrollNavTargetToTop } from '../utils/navScroll';
 /** 단추 이름에 개수를 붙인다 — 뱃지는 aria-hidden 이라 개수는 이름으로만 전해진다(BottomNav 와 같은 문구). */
 function nameWithCount(t, label, count) {
     return count && count > 0 ? t('nav.badgeLabel', { label, count, defaultValue: '{{label}}, {{count}}개' }) : label;
@@ -57,7 +58,7 @@ function SideNavButton(props) {
 /** @public */
 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 +81,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 (_) { }
+                                    scrollNavTargetToTop(scrollContainer, 'SideNav');
                                     /* 키보드로 고르면 포커스가 레일 안에 남으므로 태블릿 레일도 펼친 채 둔다(:focus-within) —
                                        아래 강제 접힘은 마우스가 들어와야 풀리므로 키보드 사용자에게 걸면 레일이 닫힌 채 포커스만 남는다. */
                                     if (!fromPointer)

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

@@ -0,0 +1,11 @@
+import type { RefObject } from 'react';
+/** 소비자가 통을 안 알려 줄 때 찾아 보는 이름 — 옛 동작 유지(말귀 셸의 본문). @internal */
+export declare const 기본통고르개 = ".content-area";
+/**
+ * 갈래를 고른 뒤 본문을 맨 위로 — 내비(SideNav·BottomNav)가 함께 쓴다. @internal
+ *
+ * 통을 못 찾으면 창을 굴리는데, 본문이 제 통에서 구르는 셸(`body { overflow: hidden }`)에서는
+ * 그것이 **아무 일도 하지 않는다** — 그때는 조용히 죽는 대신 개발 모드에 한 번 알린다.
+ * 코어가 `.content-area`(소비자 클래스 이름)를 붙잡고 있던 자리라, 부르는 쪽이 통을 알려 주는 것이 정본이다.
+ */
+export declare function scrollNavTargetToTop(scrollContainer?: string | RefObject<HTMLElement | null>, 어디서?: string): void;

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

@@ -0,0 +1,27 @@
+import { devWarnOnce } from './devWarn';
+/** 소비자가 통을 안 알려 줄 때 찾아 보는 이름 — 옛 동작 유지(말귀 셸의 본문). @internal */
+export const 기본통고르개 = '.content-area';
+/**
+ * 갈래를 고른 뒤 본문을 맨 위로 — 내비(SideNav·BottomNav)가 함께 쓴다. @internal
+ *
+ * 통을 못 찾으면 창을 굴리는데, 본문이 제 통에서 구르는 셸(`body { overflow: hidden }`)에서는
+ * 그것이 **아무 일도 하지 않는다** — 그때는 조용히 죽는 대신 개발 모드에 한 번 알린다.
+ * 코어가 `.content-area`(소비자 클래스 이름)를 붙잡고 있던 자리라, 부르는 쪽이 통을 알려 주는 것이 정본이다.
+ */
+export function scrollNavTargetToTop(scrollContainer, 어디서 = 'Nav') {
+    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('nav-scroll-container', `[${어디서}] 본문을 맨 위로 되돌릴 통을 못 찾았다(기본 ${기본통고르개}) — 창도 구를 수 없어 아무 일도 하지 않는다. scrollContainer 로 통을 알려 준다.`);
+        }
+        window.scrollTo({ top: 0 });
+    }
+    catch (_) { }
+}

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

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

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

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