@ihabdevteam/core 0.128.0 → 0.131.0

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

@@ -43,6 +43,32 @@ export function BrandIdentity({ appMode }) {
 export default function Header({ activeKey, onChange, items, malgwiItems: _malgwiItems, managerItems: _managerItems, unreadCount, onDebug, onNotification, onAccount, onSetting, onHelp, appMode, onAppModeChange }) {
     const { t } = useTranslation();
     const isMobile = useMediaQuery("(max-width: 767px)");
+    /* **모바일 하단 내비에 SideNav 항목을 옮겨 적는다.** 예전에는 `SideNavItem` 을 `NavItem` 으로
+       캐스팅만 해 넘겨, 두 타입의 이름이 다른 칸이 조용히 버려졌다 — `disabled` 가 `state` 로
+       안 가서 **비활성 항목이 모바일에서 눌렸고**, `href` 항목은 새 창 대신 `onChange(key)` 로
+       갔다. SideNav 가 거르는 구획(section)·빈 항목도 같이 거른다.
+       `badge` 는 `badgeCount` 로 옮긴다 — BottomNav 가 단추 모서리(넘치면 "…" 단추와 메뉴 항목)에
+       SideNav 와 같은 원형 숫자 배지로 그린다. 예전엔 받을 자리가 없어 숙제 개수가 모바일에서 안 보였다. */
+    const bottomItems = useMemo(() => (items ?? [])
+        .filter(it => !it.section && (it.key || it.label))
+        .map(it => ({
+        key: it.key,
+        label: typeof it.label === 'string' ? it.label : undefined,
+        icon: it.icon,
+        state: it.disabled ? 'disabled' : undefined,
+        badgeCount: it.badge,
+    })), [items]);
+    const handleBottomChange = useCallback((key) => {
+        const it = items?.find(i => i.key === key);
+        if (it?.disabled)
+            return;
+        // SideNav 와 같다 — href 가 있으면 앱 안 이동이 아니라 새 창으로 연다.
+        if (it?.href) {
+            window.open(it.href, '_blank', 'noopener,noreferrer');
+            return;
+        }
+        onChange?.(key);
+    }, [items, onChange]);
     // 모바일 하단 더보기(…) 메뉴에 노출할 유틸(알림·설정·도움말·계정·디버그).
     // 데스크톱 SideNav 푸터와 동일한 아이콘/키를 사용해 활성표시가 일관되게 반영된다.
     const bottomMoreItems = useMemo(() => {
@@ -86,7 +112,7 @@ export default function Header({ activeKey, onChange, items, malgwiItems: _malgw
                 onClick: () => { it.onClick?.(); closeUtilMenu(); },
             })),
         }], [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, { size: 48, type: "dot", shape: "pill", variant: "default", icon: 'menu', ariaLabel: t('header.menuOpen', '메뉴 열기'), onClick: toggleUtilMenu, "aria-expanded": utilOpen, "aria-controls": utilOpen ? utilMenuId : undefined }), 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: items, activeKey: activeKey ?? undefined, onChange: onChange, appMode: appMode, onAppModeChange: onAppModeChange })] }));
+    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, { size: 48, type: "dot", shape: "pill", variant: "default", icon: 'menu', ariaLabel: t('header.menuOpen', '메뉴 열기'), onClick: toggleUtilMenu, "aria-expanded": utilOpen, "aria-controls": utilOpen ? utilMenuId : undefined }), 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 })] }));
 }
 /**
  * `Header`의 alias입니다. 프로젝트 내 `Header`라는 이름이 이미 사용 중일 때 충돌 없이 임포트할 수 있습니다.

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

@@ -0,0 +1,22 @@
+/* ── Icon 마스크 모드 ────────────────────────────────────────────────
+   `.svg` 경로가 SVG 로 응답하면 Icon 은 `<span class="iconRenderer-icon-mask"
+   style="--icon-url: url(…)">` 를 그린다. 그런데 이 이름에 규칙이 하나도 없어서
+   크기 0 · 마스크 없음 — **아무것도 안 그려졌다.** Button·SideNav 는 제
+   maskClassName 에 같은 규칙을 따로 두어 괜찮았고, 기본 이름으로 쓰는 자리만 비었다.
+
+   새 색은 쓰지 않는다 — 글자색(currentColor)으로 칠해 부모의 color 를 따른다.
+   크기는 `size` prop 이 `--icon-size` 로 넘기고, 없으면 lucide 기본과 같은 20px. */
+.iconRenderer-icon-mask {
+  display: inline-block;
+  width: var(--icon-size, 20px);
+  height: var(--icon-size, 20px);
+  background-color: currentColor;
+  -webkit-mask-image: var(--icon-url);
+  -webkit-mask-repeat: no-repeat;
+  -webkit-mask-position: center;
+  -webkit-mask-size: contain;
+  mask-image: var(--icon-url);
+  mask-repeat: no-repeat;
+  mask-position: center;
+  mask-size: contain;
+}

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

@@ -1,4 +1,5 @@
 import { type ReactNode, type CSSProperties } from 'react';
+import './Icon.css';
 /** @public */
 export interface IconProps {
     /**
@@ -11,8 +12,8 @@ export interface IconProps {
     /**
      * 감싸는 `<span>` 의 클래스. 주면 기본 이름을 **갈아치운다** — 덧붙이지 않는다.
      *
-     * 기본값 `iconRenderer-icon` 을 비롯한 네 `iconRenderer-*` 이름은 **패키지에
-     * 제 규칙이 하나도 없다**(실측: 자기 규칙 0개). 붙잡을 이름일 뿐이고 크기는
+     * 기본값 `iconRenderer-icon` 을 비롯한 `iconRenderer-*` 이름은 마스크(`-mask`)를 빼면
+     * **패키지에 제 규칙이 없다**. 붙잡을 이름일 뿐이고 크기는
      * `size`, 그 밖의 모양은 `wrapperStyle` 이나 소비자 CSS 로 간다. 그래서
      * `className="iconRenderer-icon"` 이라고 적어도 아무 모양도 따라오지 않는다.
      *
@@ -23,7 +24,10 @@ export interface IconProps {
     className?: string;
     /** `<img>` 로 그릴 때의 클래스. 기본 `iconRenderer-icon-image` — 규칙 없음. */
     imgClassName?: string;
-    /** 마스크로 그릴 때의 클래스. 기본 `iconRenderer-icon-mask` — 규칙 없음. */
+    /**
+     * 마스크로 그릴 때의 클래스. 기본 `iconRenderer-icon-mask` — 글자색으로 칠하고 크기는 `size`(없으면 20px).
+     * 주면 기본 이름을 갈아치우므로 마스크 규칙(`mask-image: var(--icon-url)` 등)도 그 클래스가 대야 한다.
+     */
     maskClassName?: string;
     /** 인라인 SVG 로 그릴 때의 클래스. 기본 `iconRenderer-icon-svg` — 규칙 없음. */
     svgClassName?: string;

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

@@ -3,6 +3,7 @@ import { createElement } from 'react';
 import useLucideIcon from '../hooks/useLucideIcon';
 import useIcon from '../hooks/useIcon';
 import { resolveAssetUrl } from '../utils';
+import './Icon.css';
 /** @public */
 export default function Icon(props) {
     const { icon, label, className, imgClassName, maskClassName, svgClassName, wrapperStyle, size } = props || {};
@@ -41,7 +42,12 @@ export default function Icon(props) {
     if (iconToUse && iconToUse.endsWith('.svg')) {
         if (mode === 'mask') {
             const urlValue = blobUrl ? `url(${blobUrl})` : `url(${iconToUse})`;
-            const maskStyle = { '--icon-url': urlValue };
+            // 크기는 기본 마스크 규칙(Icon.css)이 --icon-size 로 읽는다. width/height 를 직접 박으면
+            // 제 maskClassName 으로 크기를 정하는 Button·SideNav 를 덮어 버리므로 변수로만 건넨다.
+            const maskStyle = {
+                '--icon-url': urlValue,
+                ...(typeof size === 'number' ? { '--icon-size': `${size}px` } : null),
+            };
             return createWrapper(_jsx("span", { className: defaultMaskClass, style: maskStyle }), { 'aria-hidden': 'true' });
         }
         if (mode === 'img') {

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

@@ -35,13 +35,15 @@
     box-shadow: var(--shadow-card);
 }
 
-.icon-grid-menu__button:disabled {
+/* 고른 단추 — 예전에는 `:disabled` 로 그렸다. 이제 disabled 를 쓰지 않으므로(IconGridMenu.tsx 참고)
+   같은 모양을 `--selected` 에 옮긴다. 값은 그대로. 단 `outline: none` 은 옮기지 않는다 —
+   이제 Tab 으로 닿으므로 포커스 표시가 보여야 한다. */
+.icon-grid-menu__button.icon-grid-menu__button--selected {
     cursor: default;
     opacity: 0.95;
     box-shadow: none;
     border-color: var(--color-whiteLine);
     pointer-events: none;
-    outline: none;
 }
 
 .icon-grid-menu__button-icon {

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

@@ -10,7 +10,7 @@ export interface IconGridMenuCategory {
 /** @public */
 export interface IconGridMenuProps {
     categories?: IconGridMenuCategory[];
-    /** 현재 선택된 카테고리 key (controlled) */
+    /** 현재 선택된 카테고리 key (controlled). `null` 이면 아무것도 고르지 않은 상태, 주지 않으면 첫 카테고리로 시작한다 */
     selected?: string | null;
     onSelect?: (key: string | null) => void;
     /** 버튼 크기 — `medium`(기본, 68px) / `small`(48px) */

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

@@ -11,17 +11,20 @@ function IconGridMenuButton(props) {
     // 이름표를 aria-labelledby 로 가리킨다 — label 이 문자열이 아니라 JSX 일 수도 있어
     // aria-label 로 옮겨 적는 대신 화면에 이미 있는 그 요소를 그대로 이름으로 삼는다.
     const labelId = useId();
-    return (_jsxs("div", { className: `icon-grid-menu__button-wrapper${keyClass}`, children: [_jsx("button", { className: `icon-grid-menu__button${isSelected ? ' icon-grid-menu__button--selected' : ''}`, "data-key": category?.key, onClick: isSelected ? undefined : onClick, "aria-pressed": isSelected, "aria-labelledby": labelId, disabled: isSelected, children: _jsx(Icon, { icon: category.icon, label: category.label, className: "icon-grid-menu__button-icon", imgClassName: "icon-grid-menu__button-icon-image", maskClassName: "icon-grid-menu__button-icon-mask", svgClassName: "icon-grid-menu__button-icon-svg" }) }), _jsx("span", { id: labelId, className: "icon-grid-menu__button-label button-1", children: category.label })] }));
+    return (_jsxs("div", { className: `icon-grid-menu__button-wrapper${keyClass}`, children: [_jsx("button", { className: `icon-grid-menu__button${isSelected ? ' icon-grid-menu__button--selected' : ''}`, "data-key": category?.key, type: "button", onClick: isSelected ? undefined : onClick, "aria-pressed": isSelected, "aria-labelledby": labelId, children: _jsx(Icon, { icon: category.icon, label: category.label, className: "icon-grid-menu__button-icon", imgClassName: "icon-grid-menu__button-icon-image", maskClassName: "icon-grid-menu__button-icon-mask", svgClassName: "icon-grid-menu__button-icon-svg" }) }), _jsx("span", { id: labelId, className: "icon-grid-menu__button-label button-1", children: category.label })] }));
 }
 /** @public */
 export default function IconGridMenu(props) {
     const { categories = [], selected, onSelect, size = 'medium' } = props || {};
-    const initial = selected ?? (categories && categories[0]?.key) ?? null;
+    /* `null` 은 "고르지 않음" 이라는 제어 값이다 — 첫 카테고리로 갈음하지 않는다 */
+    const initial = selected !== undefined ? selected : ((categories && categories[0]?.key) ?? null);
     const [selectedKey, setSelectedKey] = useState(initial ?? null);
     // 외부 selected prop이 controlled로 전달되면 내부 상태 동기화하는 의도된 동기화다
     /* eslint-disable react-hooks/set-state-in-effect */
     useEffect(() => {
-        if (selected !== undefined && selected !== null) {
+        /* null 도 따른다 — 예전에는 null 을 걸러 버려, 부모가 selected={null} 로 선택을 풀어도
+           단추는 골라진 채로 남았다. */
+        if (selected !== undefined) {
             setSelectedKey(selected);
         }
     }, [selected]);

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

@@ -1,6 +1,6 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useState } from 'react';
+import { useId, useState } from 'react';
 import './LandingHeader.css';
 /**
  * 랜딩/마케팅 페이지용 상단 고정 헤더.
@@ -19,6 +19,9 @@ import './LandingHeader.css';
  */
 export default function LandingHeader({ logo, logoAlt = '', logoHref, links = [], actions, className, containerClassName, renderLink, menuLabel = { open: '메뉴 열기', close: '메뉴 닫기' }, }) {
     const [open, setOpen] = useState(false);
+    // 서랍 id 를 고정 문자열로 두면 한 화면에 헤더가 둘일 때(미리보기·놀이터 견본) id 가 겹쳐
+    // 햄버거의 aria-controls 가 엉뚱한 서랍을 가리킨다 — 헤더마다 따로 짓는다.
+    const drawerId = useId();
     const innerClass = containerClassName
         ? `${containerClassName} landing-header__inner`
         : 'landing-header__inner';
@@ -34,7 +37,7 @@ export default function LandingHeader({ logo, logoAlt = '', logoHref, links = []
                         return logoHref
                             ? _jsx("a", { href: logoHref, className: "landing-header__brand", children: brand })
                             : _jsx("div", { className: "landing-header__brand", children: brand });
-                    })(), links.length > 0 && (_jsx("nav", { className: "landing-header__links", children: links.map(item => (_jsx("span", { children: link(item) }, item.href))) })), _jsxs("div", { className: "landing-header__actions", children: [actions, links.length > 0 && (_jsx("button", { type: "button", onClick: () => setOpen(v => !v), "aria-expanded": open, "aria-controls": "landing-header-drawer", "aria-label": open ? menuLabel.close : menuLabel.open, className: open
+                    })(), links.length > 0 && (_jsx("nav", { className: "landing-header__links", children: links.map(item => (_jsx("span", { children: link(item) }, item.href))) })), _jsxs("div", { className: "landing-header__actions", children: [actions, links.length > 0 && (_jsx("button", { type: "button", onClick: () => setOpen(v => !v), "aria-expanded": open, "aria-controls": drawerId, "aria-label": open ? menuLabel.close : menuLabel.open, className: open
                                     ? 'landing-header__toggle landing-header__toggle--open'
-                                    : 'landing-header__toggle', children: _jsxs("span", { className: "landing-header__burger", children: [_jsx("span", {}), _jsx("span", {}), _jsx("span", {})] }) }))] })] }), links.length > 0 && (_jsx("nav", { id: "landing-header-drawer", hidden: !open, className: "landing-header__drawer", children: _jsx("div", { className: containerClassName ?? undefined, children: links.map(item => (_jsx("span", { className: "landing-header__drawer-item", children: link(item, () => setOpen(false)) }, item.href))) }) }))] }));
+                                    : 'landing-header__toggle', children: _jsxs("span", { className: "landing-header__burger", children: [_jsx("span", {}), _jsx("span", {}), _jsx("span", {})] }) }))] })] }), links.length > 0 && (_jsx("nav", { id: drawerId, hidden: !open, className: "landing-header__drawer", children: _jsx("div", { className: containerClassName ?? undefined, children: links.map(item => (_jsx("span", { className: "landing-header__drawer-item", children: link(item, () => setOpen(false)) }, item.href))) }) }))] }));
 }

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

@@ -7,7 +7,7 @@ export interface LoaderProps {
     size?: number | string;
     /** 진행률(0–100). `variant='bar'`일 때 적용됩니다. */
     progress?: number | null;
-    /** aria-label 및 시각적 레이블 */
+    /** 접근성 이름(aria-label). 화면에 글자로 나오지는 않는다. 안 주면 i18n 의 `loader.loading`(기본 'Loading'). */
     label?: string;
 }
 /** @public */

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

@@ -1,12 +1,17 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useTranslation } from 'react-i18next';
 import './Loader.css';
 /** @public */
 export default function Loader(props) {
+    const { t } = useTranslation();
     const { variant = 'spinner', size = 24, progress = null, label } = props || {};
+    // 기본 이름이 영문 고정이라 한국어 화면에서도 낭독기가 'Loading' 으로 읽었다 — 사전을 거친다.
+    const name = label || t('loader.loading', 'Loading');
     if (variant === 'bar') {
         const pct = Math.max(0, Math.min(100, Number(progress) || 0));
-        return (_jsx("div", { className: "loader-bar", role: "progressbar", "aria-valuemin": 0, "aria-valuemax": 100, "aria-valuenow": pct, "aria-label": label || 'Loading', children: _jsx("div", { className: "loader-bar__inner", style: { width: `${pct}%` } }) }));
+        return (_jsx("div", { className: "loader-bar", role: "progressbar", "aria-valuemin": 0, "aria-valuemax": 100, "aria-valuenow": pct, "aria-label": name, children: _jsx("div", { className: "loader-bar__inner", style: { width: `${pct}%` } }) }));
     }
     const dim = typeof size === 'number' ? `${size}px` : size;
-    return (_jsx("div", { className: "loader-spinner", style: { width: dim, height: dim }, role: "status", "aria-label": label || 'Loading', children: _jsxs("svg", { className: "loader-spinner__svg", viewBox: "0 0 50 50", width: size, height: size, children: [_jsx("circle", { className: "loader-spinner__bg", cx: "25", cy: "25", r: "20", fill: "none", strokeWidth: "4" }), _jsx("circle", { className: "loader-spinner__fg", cx: "25", cy: "25", r: "20", fill: "none", strokeWidth: "4", strokeLinecap: "round" })] }) }));
+    return (_jsx("div", { className: "loader-spinner", style: { width: dim, height: dim }, role: "status", "aria-label": name, children: _jsxs("svg", { className: "loader-spinner__svg", viewBox: "0 0 50 50", width: size, height: size, children: [_jsx("circle", { className: "loader-spinner__bg", cx: "25", cy: "25", r: "20", fill: "none", strokeWidth: "4" }), _jsx("circle", { className: "loader-spinner__fg", cx: "25", cy: "25", r: "20", fill: "none", strokeWidth: "4", strokeLinecap: "round" })] }) }));
 }

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

@@ -4,9 +4,14 @@ import './NoticeBox.css';
 export interface NoticeBoxProps {
     title?: string;
     lines?: string[];
+    /** 여러 안내를 한 상자에 차례로 싣는다. 주면 `title`·`lines`·`children` 대신 이것을 그린다. */
     notices?: Array<{
         title?: string;
         lines?: string[];
+        /**
+         * 효과 없음 — 상자 모양은 바깥 `variant` 하나로만 정해진다.
+         * @deprecated 읽히지 않는 값이다. 항목마다 모양을 달리 그리는 스타일이 없다 — 모양이 다른 안내는 NoticeBox 를 따로 둔다.
+         */
         variant?: string;
         children?: ReactNode;
     }> | null;

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

@@ -15,5 +15,7 @@ export default function NoticeBox({ title = '', lines = [], notices = null, chil
         return (_jsx("div", { className: baseClass, role: "note", children: notices.map((n, idx) => (_jsxs("div", { className: "notice-box__inner", children: [n.title ? _jsx("span", { className: "notice-box__title body-3", children: n.title }) : null, _jsx("div", { className: "notice-box__body", children: n.lines && n.lines.length ? (_jsx("div", { children: n.lines.map((l, i) => (_jsx("span", { className: "notice-box__line body-3", children: l }, i))) })) : (n.children ?? null) })] }, idx))) }));
     }
     const content = (title || lines.length) ? (_jsxs("div", { className: "notice-box__inner", children: [title ? _jsx("span", { className: "notice-box__title body-1", children: title }) : null, _jsx("div", { className: "notice-box__body", children: lines.length ? (_jsx("ul", { children: lines.map((l, i) => (_jsx("li", { className: "notice-box__line", children: l }, i))) })) : children })] })) : (_jsx("div", { className: "notice-box__inner", children: children }));
-    return (_jsxs("div", { className: baseClass, role: "note", children: [content, dismissible && (_jsx("button", { className: "notice-box__dismiss", onClick: handleDismiss, "aria-label": t('common.close', '닫기'), children: "\u00D7" }))] }));
+    return (_jsxs("div", { className: baseClass, role: "note", children: [content, dismissible && (_jsx("button", { 
+                // type="button" — 없으면 폼 안에서 닫기를 누르는 순간 폼이 제출된다
+                type: "button", className: "notice-box__dismiss", onClick: handleDismiss, "aria-label": t('common.close', '닫기'), children: "\u00D7" }))] }));
 }

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

@@ -14,8 +14,8 @@ export interface PaginationProps {
     className?: string;
 }
 /**
- * 페이지네이션 컨트롤 (‹ 현재/전체 ›).
- * CustomersPage·TrainingSettingsPage 등 테이블 페이지에서 공유.
+ * 페이지네이션 컨트롤 (‹ 현재/전체 ›). 표 아래에 두고 `page`·`totalPages` 를 넘기면
+ * 이전·다음 단추가 `onChange` 로 1~`totalPages` 안의 쪽 번호를 돌려준다. 끝에서는 그쪽 단추가 꺼진다.
  *
  * @public
  */

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

@@ -5,8 +5,8 @@ import { useTranslation } from 'react-i18next';
 import Button from './Button';
 import './Pagination.css';
 /**
- * 페이지네이션 컨트롤 (‹ 현재/전체 ›).
- * CustomersPage·TrainingSettingsPage 등 테이블 페이지에서 공유.
+ * 페이지네이션 컨트롤 (‹ 현재/전체 ›). 표 아래에 두고 `page`·`totalPages` 를 넘기면
+ * 이전·다음 단추가 `onChange` 로 1~`totalPages` 안의 쪽 번호를 돌려준다. 끝에서는 그쪽 단추가 꺼진다.
  *
  * @public
  */

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

@@ -54,7 +54,11 @@ export function PanelRow(props) {
         const p = props;
         return (_jsx("div", { className: "panel-row panel-row--block", children: p.children }));
     }
-    const { variant, label, sub, onClick, required, error, align = 'horizontal', useFullWidth = false, icon } = props;
+    const { variant, label, sub, onClick: baseOnClick, required, error, align = 'horizontal', useFullWidth = false, icon } = props;
+    // button 행의 onClick 은 **단추의 것**이다(PanelRowButton.onClick). 행에도 같이 걸면
+    // 단추를 누른 클릭이 행으로 올라와 한 번 누름에 두 번 불렸다. 행 전체 클릭은 button 이 아닌
+    // variant 에서만 받는다.
+    const onClick = variant === 'button' ? undefined : baseOnClick;
     let right = null;
     // toggle 행만 왼쪽 라벨(panel-row__label)을 <label htmlFor>로 렌더해 스위치와 프로그래밍적으로
     // 연결한다 — 그 전엔 시각적으로만 옆에 붙어있어 라벨 텍스트를 클릭해도 토글이 안 되고

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

@@ -16,7 +16,12 @@ export interface PassCardProps {
     /** 기간 토큰(예: '30일'). 미지정 시 product에서 도출. */
     plan?: string;
     type?: PassCardType;
+    /**
+     * @deprecated 읽지 않는다 — 카드는 시작일을 그리지 않고, 남은 기간은 `endDate`(또는 `remainingSeconds`)로만 센다.
+     * 넘겨도 화면은 같다.
+     */
     startDate?: string;
+    /** 끝나는 날(YYYY-MM-DD). `state` 가 active·expired 이고 `remainingSeconds` 가 없으면 이 날까지 남은 날수로 사용량을 센다. */
     endDate?: string;
     /**
      * 전환으로 일시정지되어 남은 시간(초)이 알려진 경우에만 지정.
@@ -26,8 +31,12 @@ export interface PassCardProps {
      */
     remainingSeconds?: number;
     state?: PassCardState;
+    /** @deprecated 읽지 않는다 — 대기 순서는 카드에 그리지 않는다. 넘겨도 화면은 같다. */
     queueIndex?: number;
-    /** 배경 컴포넌트. 기본값: PassCardBgTwoCircle */
+    /**
+     * 배경 컴포넌트. 안 주면 종류·기간·라벨로 고른다 — 말귀(`speechear`)는 늘 PassCardBgTwoCircle,
+     * 말귀 매니저(`manager`)는 1년이면 PassCardBgTalk, 라벨이 오픈특가면 PassCardBgSoundMoveV1, 그 밖에는 PassCardBgSoundMove.
+     */
     bg?: ReactNode;
     /** true면 배경만 표시하고 콘텐츠(로고·플랜·카피라이트)를 숨김 */
     bgOnly?: boolean;

package/dist/packages/core/src/components/PassCard/PassCardBg.css

@@ -37,3 +37,36 @@
   -webkit-mask: var(--symbol-url) center / contain no-repeat;
   mask: var(--symbol-url) center / contain no-repeat;
 }
+
+/* ── PassCardBg 컴포넌트 자체의 변형(default · blue · dark) ─────────────────
+   9종 배경은 각자 파일에 모양을 두고, 이 기본 컴포넌트의 원 셋과 변형은 규칙이 없어
+   세 변형이 똑같이(빈 바탕으로) 그려졌다(2026-09-14, 사용자가 정하도록 맡김).
+   **새 색은 쓰지 않는다** — 원 구도는 PassCardBgTwoCircle 과 같게(큰 원 우상단 · 작은 원
+   우하단)에 좌하단 원 하나를 더하고, 색은 브랜드·중립 토큰만 쓴다. 만료 카드
+   (.pass-card--expired)가 --color-main/sub 를 회색으로 바꾸는 규칙도 그대로 따라온다. */
+.pass-card-bg__circle {
+  position: absolute;
+  border-radius: 50%;
+  opacity: var(--pass-card-symbol-opacity, 0.75);
+}
+.pass-card-bg__circle--1 { width: 340px; height: 340px; top: -140px; right: -150px; }
+.pass-card-bg__circle--2 { width: 220px; height: 220px; bottom: -90px; right: -50px; }
+.pass-card-bg__circle--3 { width: 140px; height: 140px; bottom: -70px; left: -40px; }
+
+/* default — 흰 바탕 + main · sub 원(TwoCircle 과 같은 결) */
+.pass-card-bg--default { background: var(--color-pureWhite); }
+.pass-card-bg--default .pass-card-bg__circle--1 { background: var(--color-main); }
+.pass-card-bg--default .pass-card-bg__circle--2 { background: var(--color-sub); }
+.pass-card-bg--default .pass-card-bg__circle--3 { background: var(--color-main-a20); }
+
+/* blue — 짙은 main 바탕 + 흰 반투명 원 */
+.pass-card-bg--blue { background: var(--color-deepMain); }
+.pass-card-bg--blue .pass-card-bg__circle--1 { background: var(--color-white-a30); }
+.pass-card-bg--blue .pass-card-bg__circle--2 { background: var(--color-white-a10); }
+.pass-card-bg--blue .pass-card-bg__circle--3 { background: var(--color-white-a10); }
+
+/* dark — 검은 바탕 + main · sub 원 */
+.pass-card-bg--dark { background: var(--color-softBlack); }
+.pass-card-bg--dark .pass-card-bg__circle--1 { background: var(--color-main); }
+.pass-card-bg--dark .pass-card-bg__circle--2 { background: var(--color-sub); }
+.pass-card-bg--dark .pass-card-bg__circle--3 { background: var(--color-white-a10); }

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

@@ -26,8 +26,15 @@ export interface PaymentPlanTier {
 export interface PaymentPlanData {
     id: string | number;
     title?: string;
-    /** 서비스명(말귀/말귀매니저). 카드 로고·표기용. title에서 파싱하지 않고 별도 저장. */
+    /**
+     * 서비스명(말귀/말귀매니저). 이 컴포넌트는 읽지 않는다 — 카드 로고는 `group` 으로 고른다.
+     * 부르는 쪽이 상품 목록을 나누거나 표기할 때 쓰도록 자리만 둔 칸이다.
+     */
     service?: string;
+    /**
+     * 상품 묶음. `'org'` 면 이용권 카드를 말귀 매니저 모양으로, 그 밖(`'personal'` 등)이면 말귀 모양으로 그린다.
+     */
+    group?: 'personal' | 'org' | (string & {});
     /** 플랜 티어명(스탠다드/라이트/프로 등). 카드 헤드라인용. */
     tier?: string;
     subtitle?: string;

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

@@ -59,7 +59,7 @@ export interface ConfirmPopupProps {
     onClose: () => void;
     /** portal 없이 부모 컨테이너에 제자리 렌더 (목업/데모용) */
     inline?: boolean;
-    /** 패널 최대 가로폭. 확인창 기본은 'small'(640px) */
+    /** 패널 최대 가로폭. 확인창 기본은 'small'(480px) */
     size?: 'small' | 'medium' | 'large';
     className?: string;
 }

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

@@ -40,7 +40,14 @@ export interface PopupListProps<T extends {
     selectedId?: string | number;
     /** 현재 선택된 아이템 id Set — 다중 선택 강조 (`selectedId`보다 우선) */
     selectedIds?: Set<string | number>;
-    /** 행 클릭 후에도 팝업을 닫지 않음 (다중 선택용). 기본 false */
+    /**
+     * 효과 없음 — ListPopup 은 행을 골라도 **스스로 닫지 않는다**(닫기는 늘 `onSelect`·`onClose` 를
+     * 받은 쪽이 정한다). 그래서 이 값은 읽지 않는다.
+     *
+     * @deprecated 읽히지 않는 값이다. 예전 JSDoc 은 "기본 false = 고르면 닫힘" 이라 했지만 그렇게
+     * 동작한 적이 없고, 그 뜻대로 고치면 행 클릭이 아무것도 안 하는 화면(행 안 단추로만 보내는 창 등)이
+     * 누르는 순간 닫힌다. 고른 뒤 닫으려면 `onSelect` 안에서 직접 닫는다.
+     */
     keepOpenOnSelect?: boolean;
     /** 행 선택 콜백 */
     onSelect: (item: T) => void;

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

@@ -63,12 +63,27 @@ export default function ListPopup(props) {
     }, [sortKey]);
     // countLabel("총 {n}명")을 Toolbar count의 prefix/suffix로 분해
     const countParts = useMemo(() => {
+        /* 함수 꼴은 예전에 통째로 무시되어 기본 "총 N개" 가 떴다(JSDoc 은 받는다고 했다).
+           Toolbar 는 숫자를 강조 칸에 따로 그리므로, 돌려받은 문자열에서 개수가 **마지막으로**
+           나오는 자리를 갈라 앞·뒤로 넘긴다 — 앞+숫자+뒤가 언제나 원래 문자열과 같아서
+           글은 틀리지 않는다(숫자가 여럿이면 강조 자리만 어긋날 수 있다). 문자열이 아니거나
+           개수가 안 들어 있으면 가를 수 없으니 받은 것을 그대로 그린다. */
+        if (typeof countLabel === 'function') {
+            const n = filtered.length;
+            const label = countLabel(n);
+            if (typeof label === 'string') {
+                const at = label.lastIndexOf(String(n));
+                if (at >= 0)
+                    return { prefix: label.slice(0, at), suffix: label.slice(at + String(n).length) };
+            }
+            return { label };
+        }
         if (typeof countLabel === 'string' && countLabel.includes('{n}')) {
             const [prefix, suffix] = countLabel.split('{n}');
             return { prefix, suffix };
         }
         return { prefix: t('common.totalCountPrefix', '총 '), suffix: t('common.totalCountSuffix', '개') };
-    }, [countLabel, t]);
+    }, [countLabel, filtered.length, t]);
     const tableFields = useMemo(() => columns.map(col => ({
         label: col.label,
         onClick: col.sortable !== false ? () => handleSort(col.key) : undefined,
@@ -76,7 +91,7 @@ export default function ListPopup(props) {
         sortDir: col.sortable !== false && sortKey === col.key ? (sortAsc ? 'asc' : 'desc') : null,
     })), [columns, sortKey, sortAsc, handleSort]);
     const pageSizeOpts = useMemo(() => pageSizeOptions.map(n => ({ value: String(n), label: t('common.pageSizeLabel', { n }) })), [pageSizeOptions, t]);
-    return (_jsxs(Popup, { className: `popup-list ${className}`, title: title, onClose: onClose, children: [topContent, _jsx(Toolbar, { count: { value: filtered.length, prefix: countParts.prefix, suffix: countParts.suffix }, search: searchEnabled ? { value: search, onChange: setSearch, placeholder: resolvedSearchPlaceholder } : undefined, pageSize: { options: pageSizeOpts, value: pageSize, onChange: setPageSize }, pagination: { page, total: totalPages, onChange: setPage } }), _jsx(Table, { size: "medium", gridTemplateColumns: gridTemplateColumns, resizable: true, fields: tableFields, items: paged, onRowClick: onSelect, renderRow: (it) => {
+    return (_jsxs(Popup, { className: `popup-list ${className}`, title: title, onClose: onClose, children: [topContent, 'label' in countParts && _jsx("p", { className: "toolbar__count body-1", children: countParts.label }), _jsx(Toolbar, { count: 'label' in countParts ? undefined : { value: filtered.length, prefix: countParts.prefix, suffix: countParts.suffix }, search: searchEnabled ? { value: search, onChange: setSearch, placeholder: resolvedSearchPlaceholder } : undefined, pageSize: { options: pageSizeOpts, value: pageSize, onChange: setPageSize }, pagination: { page, total: totalPages, onChange: setPage } }), _jsx(Table, { size: "medium", gridTemplateColumns: gridTemplateColumns, resizable: true, fields: tableFields, items: paged, onRowClick: onSelect, renderRow: (it) => {
                     const isSelected = selectedIds != null
                         ? (it.id != null && selectedIds.has(it.id))
                         : (selectedId != null && it.id === selectedId);

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

@@ -30,7 +30,7 @@
   display: flex;
   flex-direction: column;
 }
-/* size별 최대 가로폭 — 미지정 시 위의 기본(820px) 유지. 앱의 기존 팝업 폭(480/680/880)에 정렬 */
+/* size별 최대 가로폭 — 미지정 시 위의 기본(820px) 유지. small 480 · medium 680 · large 1080 */
 .popup-panel--small  { max-width: 480px; }
 .popup-panel--medium { max-width: 680px; }
 .popup-panel--large  { max-width: 1080px; }

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

@@ -69,7 +69,7 @@ export interface PopupProps {
      * 패널 최대 가로폭 제한. 미지정 시 기본(820px) 유지.
      * - `small`  480px (확인/알림류)
      * - `medium` 680px (입력 폼)
-     * - `large`  880px (리스트/다중 콘텐츠)
+     * - `large`  1080px (리스트/다중 콘텐츠)
      * 더 넓거나 무제한이 필요하면 className으로 `.popup-panel` max-width를 직접 override.
      */
     size?: 'small' | 'medium' | 'large';

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

@@ -81,14 +81,15 @@ export default function TrainingResultPopup(props) {
     const list = useMemo(() => Array.isArray(results) ? results : [], [results]);
     const rows = useMemo(() => list.map((it) => {
         const itr = it ?? {};
-        const problem = resolveProblem(itr) || '(내용없음)';
+        // 문제 글이 비었을 때의 자리표시도 번역을 거친다 — 영어 화면에 한국어가 박혀 나왔다
+        const problem = resolveProblem(itr) || t('training.result.noContent', '(내용없음)');
         const { variant, label } = getJudge(itr);
         const corrects = Array.isArray(itr.corrects) ? itr.corrects : [];
         const answer = corrects.length ? corrects.join(', ') : (itr.answer != null && itr.answer !== '' ? String(itr.answer) : null);
         const selectedText = typeof itr.selectedText === 'string' ? itr.selectedText : null;
         const isCorrect = resolveDecision(itr) === true;
         return { problem, variant, label, answer, selectedText, isCorrect };
-    }), [list, getJudge]);
+    }), [list, getJudge, t]);
     const hasAnswerCols = useMemo(() => rows.some(r => r.answer !== null || r.selectedText !== null), [rows]);
     // 스크롤은 Popup의 .popup-content 하나만 담당한다 — 예전엔 결과 카드가 자체 스크롤
     // 래퍼(.trp-result__scroll)를 하나 더 두어 이중 스크롤이 됐고, 안쪽이 overscroll:contain으로

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

@@ -4,9 +4,12 @@ interface WordDataUpdatePopupProps {
     title: string;
     progress: WordDataProgress;
     onDone: () => void;
+    /** 오류 때 '다시 시도' 단추가 부른다. 없으면 그 자리에 '닫기' 단추가 선다. */
     onRetry?: () => void;
+    /** 오류인데 `onRetry` 가 없을 때 '닫기' 단추가 부른다. 없으면 `onDone` 을 부른다. */
+    onClose?: () => void;
     inline?: boolean;
 }
 /** @public */
-export default function WordDataUpdatePopup({ title, progress, onDone, onRetry, inline }: WordDataUpdatePopupProps): import("react").JSX.Element;
+export default function WordDataUpdatePopup({ title, progress, onDone, onRetry, onClose, inline }: WordDataUpdatePopupProps): import("react").JSX.Element;
 export {};

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

@@ -37,7 +37,7 @@ function PhaseCard({ icon, label, state, pct, subText }) {
                                     : (subText || pct !== undefined) && (_jsxs("span", { className: "wdup-phase-card__sub body-3", children: [subText, subText && pct !== undefined ? ` · ${pct}%` : pct !== undefined ? `${pct}%` : ''] }))] }), !isPending && (_jsx("div", { className: "wdup-bar", children: _jsx("div", { className: `wdup-bar__fill${isDone ? ' wdup-bar__fill--done' : isError ? ' wdup-bar__fill--error' : ''}${state === 'active' && pct === undefined ? ' wdup-bar__fill--indeterminate' : ''}`, style: { width: pct !== undefined || isDone || isError ? `${isError ? 100 : barPct}%` : undefined } }) }))] })] }));
 }
 /** @public */
-export default function WordDataUpdatePopup({ title, progress, onDone, onRetry, inline }) {
+export default function WordDataUpdatePopup({ title, progress, onDone, onRetry, onClose, inline }) {
     const { t } = useTranslation();
     const { phase, error, wordCount, imagePage, imageDone, imageTotal, pairPercent } = progress;
     const order = phaseOrder(phase);
@@ -67,7 +67,12 @@ export default function WordDataUpdatePopup({ title, progress, onDone, onRetry,
             return t('wordData.imageCount', { done: formatCount(imageDone), total: formatCount(imageTotal) });
         return undefined;
     }, [imgState, phase, imagePage, imageTotal, imageDone, t]);
-    return (_jsx(Popup, { inline: inline, className: "popup--word-data-update", title: title, footer: isError
+    return (_jsx(Popup, { inline: inline, className: "popup--word-data-update", title: title, footer: 
+        /* 오류인데 다시 시도할 곳이 없으면 '다시 시도' 가 아무 일도 안 하고, 이 팝업은 X 도
+           Esc 도 없어 **빠져나갈 길이 없었다**. 그때만 닫기 단추로 바꾼다. */
+        isError && onRetry
             ? _jsx(Button, { size: 56, variant: "main", onClick: onRetry, children: t('common.retry', '다시 시도') })
-            : _jsx(Button, { size: 56, variant: "main", disabled: !isDone, onClick: onDone, children: t('common.done', '완료') }), children: _jsxs("div", { className: "wdup-cards", children: [_jsx(PhaseCard, { icon: _jsx(Database, { size: 22, color: "var(--color-main, #29b6c8)", strokeWidth: 1.8 }), label: t('wordData.phaseWordDownload', '단어 데이터 다운로드'), state: wordState, subText: wordState === 'active' ? t('wordData.downloadingCount', { n: formatCount(wordCount) }) : undefined }), _jsx(PhaseCard, { icon: _jsx(ImageIcon, { size: 22, color: "var(--color-main, #29b6c8)", strokeWidth: 1.8 }), label: t('wordData.phaseImageCheck', '이미지 확인'), state: imgState, pct: imgPct, subText: imgSub }), _jsx(PhaseCard, { icon: _jsx(GitMerge, { size: 22, color: "var(--color-main, #29b6c8)", strokeWidth: 1.8 }), label: t('wordData.phasePairAnalysis', '단어쌍 분석'), state: pairState, pct: pairState === 'active' ? (pairPercent ?? 0) : undefined, subText: undefined })] }) }));
+            : isError
+                ? _jsx(Button, { size: 56, variant: "main", onClick: onClose ?? onDone, children: t('common.close', '닫기') })
+                : _jsx(Button, { size: 56, variant: "main", disabled: !isDone, onClick: onDone, children: t('common.done', '완료') }), children: _jsxs("div", { className: "wdup-cards", children: [_jsx(PhaseCard, { icon: _jsx(Database, { size: 22, color: "var(--color-main, #29b6c8)", strokeWidth: 1.8 }), label: t('wordData.phaseWordDownload', '단어 데이터 다운로드'), state: wordState, subText: wordState === 'active' ? t('wordData.downloadingCount', { n: formatCount(wordCount) }) : undefined }), _jsx(PhaseCard, { icon: _jsx(ImageIcon, { size: 22, color: "var(--color-main, #29b6c8)", strokeWidth: 1.8 }), label: t('wordData.phaseImageCheck', '이미지 확인'), state: imgState, pct: imgPct, subText: imgSub }), _jsx(PhaseCard, { icon: _jsx(GitMerge, { size: 22, color: "var(--color-main, #29b6c8)", strokeWidth: 1.8 }), label: t('wordData.phasePairAnalysis', '단어쌍 분석'), state: pairState, pct: pairState === 'active' ? (pairPercent ?? 0) : undefined, subText: undefined })] }) }));
 }

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

@@ -26,5 +26,10 @@ export declare function visitItemKey(v: {
     hour: string;
     minute: string;
 }): string;
-/** 초 → "M분 S초"(또는 "S초") */
-export declare function formatDuration(sec: number | null | undefined): string;
+/**
+ * 초 → "M분 S초"(또는 "M분"·"S초"). 없거나 0 이하면 '-'.
+ *
+ * 문구는 지금 언어로(`customers.duration.*`, 사전에 없으면 한국어). `durationStr` 를 주면
+ * 그 함수가 만든 글을 그대로 쓴다 — `calcAge` 의 `ageStr` 와 같은 결.
+ */
+export declare function formatDuration(sec: number | null | undefined, durationStr?: (m: number, s: number) => string): string;

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

@@ -2,7 +2,12 @@
  * customerDetailUtils.ts
  * CustomerDetailPopup의 순수 표시/포맷 유틸 (상태 비의존).
  */
+import i18n from 'i18next';
 import { getTodayKst } from '../../utils/date';
+/** i18n 이 아직 안 섰으면(초기화 전 `i18n.t` 는 undefined) 한국어 기본값을 직접 채운다. */
+function 번역됐거나(s, 기본, vars) {
+    return typeof s === 'string' && s ? s : 기본.replace(/\{\{(\w+)\}\}/g, (_, k) => String(vars[k]));
+}
 export function getDayOptions(year, month, daySuffix) {
     const days = new Date(Number(year), Number(month), 0).getDate();
     return Array.from({ length: days }, (_, i) => {
@@ -65,11 +70,23 @@ export function formatId(id) {
 export function visitItemKey(v) {
     return `${v.year}-${v.month}-${v.day}T${v.hour}:${v.minute}`;
 }
-/** 초 → "M분 S초"(또는 "S초") */
-export function formatDuration(sec) {
+/**
+ * 초 → "M분 S초"(또는 "M분"·"S초"). 없거나 0 이하면 '-'.
+ *
+ * 문구는 지금 언어로(`customers.duration.*`, 사전에 없으면 한국어). `durationStr` 를 주면
+ * 그 함수가 만든 글을 그대로 쓴다 — `calcAge` 의 `ageStr` 와 같은 결.
+ */
+export function formatDuration(sec, durationStr) {
     if (!sec || sec <= 0)
         return '-';
     const m = Math.floor(sec / 60);
     const s = sec % 60;
-    return m > 0 ? `${m}분${s > 0 ? ` ${s}초` : ''}` : `${s}초`;
+    if (durationStr)
+        return durationStr(m, s);
+    // 열쇠를 글자로 적어 둔다 — test/i18nKeysExist 가 사전에 있는지 훑는다
+    if (m > 0 && s > 0)
+        return 번역됐거나(i18n.t('customers.duration.minSec', { m, s, defaultValue: '{{m}}분 {{s}}초' }), '{{m}}분 {{s}}초', { m, s });
+    if (m > 0)
+        return 번역됐거나(i18n.t('customers.duration.min', { m, defaultValue: '{{m}}분' }), '{{m}}분', { m });
+    return 번역됐거나(i18n.t('customers.duration.sec', { s, defaultValue: '{{s}}초' }), '{{s}}초', { s });
 }