@ihabdevteam/core 0.173.0 → 0.175.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;
 
 /**
@@ -1056,7 +1063,7 @@ export declare interface ChartPoint {
  * 공유하도록 두 컴포넌트가 내부적으로 사용한다.
  * @public
  */
-export declare function ChartSection({ title, titleClassName, icon, disc, headRight, headSegment, headMenuItems, collapseBelow, onClick, ariaLabel, tooltip, subRow, className, inGrid, children }: ChartSectionProps): JSX.Element;
+export declare function ChartSection({ title, titleClassName, icon, disc, headRight, headSegment, headMenuItems, collapseBelow, onClick, ariaLabel, tooltip, totalNum, totalUnit, totalLabel, subRow, className, inGrid, children }: ChartSectionProps): JSX.Element;
 
 /** @public */
 export declare interface ChartSectionProps {
@@ -1084,6 +1091,13 @@ export declare interface ChartSectionProps {
     onClick?: () => void;
     /** 누르는 카드의 이름(낭독기) — 안 주면 제목이 글자일 때 그것을 쓴다 */
     ariaLabel?: string;
+    /** 머리 오른쪽에 **한 줄로** 세우는 수(예: 정답률 83). 앞에 설명(`totalLabel`), 뒤에 큰 수와 단위(`totalUnit`).
+     *  `ChartTotal` 은 아래 줄(`subRow`)의 꼴이고, 이것은 **머리 줄** 의 꼴이다 — 소비자가 손으로 짜던 자리. */
+    totalNum?: ReactNode;
+    /** 수 뒤 단위(`%` 등) — `totalNum` 과 함께 쓴다 */
+    totalUnit?: ReactNode;
+    /** 수 앞 설명 한 줄 — 색을 입힌 대비 수치 등은 노드로 넘긴다(앱 규칙) */
+    totalLabel?: ReactNode;
     /** 카드에 포인터가 닿을 때(키보드는 초점이 들어올 때) 뜨는 설명 — `StatChart tooltip` 과 같은 뜻.
      *  같은 줄에 선 StatChart 카드들만 설명이 뜨고 이 카드만 안 뜨던 것을 메운다. */
     tooltip?: string;
@@ -1556,7 +1570,7 @@ export declare function copyText(text: string): Promise<boolean>;
  *
  * 값은 손으로 적고 `test/coreVersion.test.ts` 가 package.json 과 어긋나면 운다.
  */
-export declare const CORE_VERSION = "0.173.0";
+export declare const CORE_VERSION = "0.175.0";
 
 /** @public */
 declare const coreDefault: Record<string, unknown>;
@@ -2682,7 +2696,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 +2716,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 */
@@ -5926,6 +5947,7 @@ export declare type ShuffledItem = {
 
 declare type Side = '좌' | '우';
 
+/** @public */
 export declare function SideNav(props: SideNavProps): React_2.JSX.Element;
 
 /** @public */

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/ChartSection.css

@@ -65,6 +65,31 @@
   color: var(--color-gray);
   margin: 0;
 }
+/* 머리 오른쪽의 수 — 앞에 설명, 뒤에 큰 수. **수는 줄을 안 넘긴다**(설명만 줄어든다) */
+.manager-section__head-total {
+  display: flex;
+  align-items: baseline;
+  gap: var(--spacing-xs);
+  min-width: 0;
+}
+.manager-section__head-total-label {
+  color: var(--color-gray);
+  min-width: 0;
+}
+.manager-section__head-total-value {
+  display: flex;
+  align-items: baseline;
+  gap: 2px;
+  white-space: nowrap;
+  flex-shrink: 0;
+}
+.manager-section__head-total-num {
+  color: var(--color-black);
+}
+.manager-section__head-total-unit {
+  color: var(--color-gray);
+}
+
 .manager-section__head-right {
   display: flex;
   align-items: center;

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

@@ -61,6 +61,13 @@ export interface ChartSectionProps {
     onClick?: () => void;
     /** 누르는 카드의 이름(낭독기) — 안 주면 제목이 글자일 때 그것을 쓴다 */
     ariaLabel?: string;
+    /** 머리 오른쪽에 **한 줄로** 세우는 수(예: 정답률 83). 앞에 설명(`totalLabel`), 뒤에 큰 수와 단위(`totalUnit`).
+     *  `ChartTotal` 은 아래 줄(`subRow`)의 꼴이고, 이것은 **머리 줄** 의 꼴이다 — 소비자가 손으로 짜던 자리. */
+    totalNum?: ReactNode;
+    /** 수 뒤 단위(`%` 등) — `totalNum` 과 함께 쓴다 */
+    totalUnit?: ReactNode;
+    /** 수 앞 설명 한 줄 — 색을 입힌 대비 수치 등은 노드로 넘긴다(앱 규칙) */
+    totalLabel?: ReactNode;
     /** 카드에 포인터가 닿을 때(키보드는 초점이 들어올 때) 뜨는 설명 — `StatChart tooltip` 과 같은 뜻.
      *  같은 줄에 선 StatChart 카드들만 설명이 뜨고 이 카드만 안 뜨던 것을 메운다. */
     tooltip?: string;
@@ -83,4 +90,4 @@ export interface ChartSectionProps {
  * 공유하도록 두 컴포넌트가 내부적으로 사용한다.
  * @public
  */
-export default function ChartSection({ title, titleClassName, icon, disc, headRight, headSegment, headMenuItems, collapseBelow, onClick, ariaLabel, tooltip, subRow, className, inGrid, children }: ChartSectionProps): import("react").JSX.Element;
+export default function ChartSection({ title, titleClassName, icon, disc, headRight, headSegment, headMenuItems, collapseBelow, onClick, ariaLabel, tooltip, totalNum, totalUnit, totalLabel, subRow, className, inGrid, children }: ChartSectionProps): import("react").JSX.Element;

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

@@ -27,7 +27,7 @@ export function ChartTotal({ label, children }) {
  * 공유하도록 두 컴포넌트가 내부적으로 사용한다.
  * @public
  */
-export default function ChartSection({ title, titleClassName = 'h3', icon, disc, headRight, headSegment, headMenuItems, collapseBelow = 420, onClick, ariaLabel, tooltip, subRow, className, inGrid = false, children }) {
+export default function ChartSection({ title, titleClassName = 'h3', icon, disc, headRight, headSegment, headMenuItems, collapseBelow = 420, onClick, ariaLabel, tooltip, totalNum, totalUnit, totalLabel, subRow, className, inGrid = false, children }) {
     const { t } = useTranslation();
     const secRef = useRef(null);
     /* 설명 툴팁 — StatChart 와 같은 결(카드 사각형 기준, 포인터가 나가거나 초점이 빠지면 닫힘).
@@ -93,7 +93,10 @@ export default function ChartSection({ title, titleClassName = 'h3', icon, disc,
         }
     }, [onClick]);
     const 오른쪽 = typeof headRight === 'function' ? headRight({ collapsed: 접힘 }) : headRight;
-    const 머리오른쪽 = (오른쪽 || headSegment) ? (_jsxs("div", { className: "manager-section__head-right", children: [오른쪽, headSegment && (접힘 ? (_jsx(Button, { htmlType: "button", size: 32, type: "dot", icon: "ellipsis", ariaLabel: headSegment.ariaLabel ?? t('common.more', '더보기'), showTooltipInfo: headSegment.ariaLabel ?? t('common.more', '더보기'), "aria-haspopup": "menu", "aria-expanded": !!메뉴자리, onClick: 메뉴열기 })) : (_jsx(SegmentedControl, { size: 32, ariaLabel: headSegment.ariaLabel, options: headSegment.options.map(o => ({ key: o.key, label: o.label, disabled: o.disabled })), value: headSegment.value, onChange: headSegment.onChange })))] })) : null;
+    /* 머리 오른쪽 차례 — **수 → 고르개 → 나머지(상세보기 단추가 맨 끝)**.
+       전에는 `headRight` 를 먼저 그려 상세보기 단추가 고르개 **앞** 에 섰다(사용자 지시 2026-09-17: 단추가 오른쪽 끝). */
+    const 머리수 = (totalNum != null || totalLabel) ? (_jsxs("div", { className: "manager-section__head-total", children: [totalLabel && _jsx("span", { className: "manager-section__head-total-label caption-1", children: totalLabel }), totalNum != null && (_jsxs("span", { className: "manager-section__head-total-value", children: [_jsx("span", { className: "manager-section__head-total-num h4", children: totalNum }), totalUnit && _jsx("span", { className: "manager-section__head-total-unit h5", children: totalUnit })] }))] })) : null;
+    const 머리오른쪽 = (오른쪽 || headSegment || 머리수) ? (_jsxs("div", { className: "manager-section__head-right", children: [머리수, headSegment && (접힘 ? (_jsx(Button, { htmlType: "button", size: 32, type: "dot", icon: "ellipsis", ariaLabel: headSegment.ariaLabel ?? t('common.more', '더보기'), showTooltipInfo: headSegment.ariaLabel ?? t('common.more', '더보기'), "aria-haspopup": "menu", "aria-expanded": !!메뉴자리, onClick: 메뉴열기 })) : (_jsx(SegmentedControl, { size: 32, ariaLabel: headSegment.ariaLabel, options: headSegment.options.map(o => ({ key: o.key, label: o.label, disabled: o.disabled })), value: headSegment.value, onChange: headSegment.onChange }))), 오른쪽] })) : null;
     return (_jsxs("section", { ref: secRef, className: ['manager-section', inGrid && 'manager-section--grid', onClick && 'manager-section--clickable', className].filter(Boolean).join(' '), onClick: onClick ? 카드누름 : undefined, onKeyDown: onClick ? 카드키 : undefined, onPointerEnter: tooltip ? 설명보이기 : undefined, onPointerLeave: tooltip ? 설명닫기 : undefined, onFocus: tooltip ? 설명보이기 : undefined, onBlur: tooltip ? 설명닫기 : undefined, role: onClick ? 'button' : undefined, tabIndex: onClick ? 0 : undefined, "aria-label": onClick ? (ariaLabel ?? (typeof title === 'string' ? title : undefined)) : undefined, children: [tooltip && 설명자리 && (_jsx(TooltipInfo, { anchorRect: {
                     left: 설명자리.left,
                     top: 설명자리.top + 21,

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

@@ -36,4 +36,5 @@ export interface SideNavProps {
      */
     scrollContainer?: string | RefObject<HTMLElement | null>;
 }
+/** @public */
 export default function SideNav(props: SideNavProps): React.JSX.Element;

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

@@ -7,7 +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';
+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;
@@ -56,30 +56,6 @@ 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, scrollContainer } = props || {};
@@ -105,7 +81,7 @@ export default function SideNav(props) {
                                         return;
                                     }
                                     onChange?.(it.key);
-                                    맨위로(scrollContainer);
+                                    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.173.0";
+export declare const CORE_VERSION = "0.175.0";

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

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