@ihabdevteam/core 0.169.0 → 0.171.0

package/dist/ihabdevteam-core.d.ts

@@ -1,4 +1,4 @@
-import type { ComponentType } from 'react';
+import { ComponentType } from 'react';
 import { Context } from 'react';
 import { CSSProperties } from 'react';
 import { Dispatch } from 'react';
@@ -10,6 +10,7 @@ import { ForwardRefExoticComponent } from 'react';
 import type { HTMLAttributes } from 'react';
 import { JSX } from 'react';
 import { KeyboardEvent as KeyboardEvent_2 } from 'react';
+import { LazyExoticComponent } from 'react';
 import { MouseEvent as MouseEvent_2 } from 'react';
 import { default as React_2 } from 'react';
 import * as React_3 from 'react';
@@ -309,7 +310,7 @@ export declare type BadgeType = 'bar' | 'dot';
  *  - 주(week):  'YYYY년 M월 N째주' 드롭다운 + 그 주의 요일(월~일) 막대
  * 원시 렌더링은 내부 BarChartCanvas가 담당한다.
  */
-export declare function BarChart({ size, barWidth, titleKey, data, colorA, colorB, labelAKey, labelBKey, showTotal, totalUnitKey, totalLabelKey, control: controlProp, hideControls, rate, rateAgg, tightMax, avgMode, totalFormat, series, seriesMode, loading, onDetail, headExtra, headSegment, icon, disc, onClick, cardAriaLabel, detailSize, barGap, baseline, className, inGrid, }: BarChartProps): JSX.Element;
+export declare function BarChart({ size, barWidth, titleKey, data, colorA, colorB, labelAKey, labelBKey, showTotal, totalUnitKey, totalLabelKey, control: controlProp, hideControls, rate, rateAgg, tightMax, avgMode, totalFormat, series, seriesMode, loading, onDetail, headExtra, headSegment, icon, disc, onClick, cardAriaLabel, cardTooltip, detailSize, barGap, baseline, className, inGrid, }: BarChartProps): JSX.Element;
 
 /** @public */
 export declare interface BarChartControl {
@@ -417,6 +418,8 @@ export declare interface BarChartProps {
     onClick?: () => void;
     /** 누르는 카드의 이름(낭독기) — 안 주면 제목 */
     cardAriaLabel?: string;
+    /** 카드에 포인터가 닿을 때(키보드는 초점) 뜨는 설명 — StatChart tooltip 과 같은 뜻 */
+    cardTooltip?: string;
     /** 제목 왼쪽 아이콘 — Section·ChartSection 과 같은 자리·같은 색 */
     icon?: string;
     /** 제목 아래 설명 한 줄 */
@@ -1053,7 +1056,7 @@ export declare interface ChartPoint {
  * 공유하도록 두 컴포넌트가 내부적으로 사용한다.
  * @public
  */
-export declare function ChartSection({ title, titleClassName, icon, disc, headRight, headSegment, headMenuItems, collapseBelow, onClick, ariaLabel, subRow, className, inGrid, children }: ChartSectionProps): JSX.Element;
+export declare function ChartSection({ title, titleClassName, icon, disc, headRight, headSegment, headMenuItems, collapseBelow, onClick, ariaLabel, tooltip, subRow, className, inGrid, children }: ChartSectionProps): JSX.Element;
 
 /** @public */
 export declare interface ChartSectionProps {
@@ -1081,6 +1084,9 @@ export declare interface ChartSectionProps {
     onClick?: () => void;
     /** 누르는 카드의 이름(낭독기) — 안 주면 제목이 글자일 때 그것을 쓴다 */
     ariaLabel?: string;
+    /** 카드에 포인터가 닿을 때(키보드는 초점이 들어올 때) 뜨는 설명 — `StatChart tooltip` 과 같은 뜻.
+     *  같은 줄에 선 StatChart 카드들만 설명이 뜨고 이 카드만 안 뜨던 것을 메운다. */
+    tooltip?: string;
     /** 총계(ChartTotal) + 범례(ChartLegend)를 담는 서브로우 */
     subRow?: ReactNode;
     /** 섹션 루트에 추가할 클래스 */
@@ -1550,7 +1556,7 @@ export declare function copyText(text: string): Promise<boolean>;
  *
  * 값은 손으로 적고 `test/coreVersion.test.ts` 가 package.json 과 어긋나면 운다.
  */
-export declare const CORE_VERSION = "0.169.0";
+export declare const CORE_VERSION = "0.171.0";
 
 /** @public */
 declare const coreDefault: Record<string, unknown>;
@@ -3008,6 +3014,29 @@ export declare interface LandingHeaderProps {
     };
 }
 
+/**
+ * 화면을 늦게 받아 오는 자리 — `lazy()` 를 그냥 쓰지 않고 이걸 쓴다.
+ *
+ * 맨 `lazy(() => import(…))` 는 **모듈이 undefined 로 와도 그대로 `.default` 를 읽는다.**
+ * 그 일이 실제로 난다: 배포 skew 복구가 `vite:preloadError` 를 `preventDefault()` 하면
+ * Vite 헬퍼의 `catch` 가 아무것도 안 던지고 undefined 로 resolve 한다(자세한 것은
+ * `chunkSkew.ts`). 그러면 새로고침이 이미 걸려 있는데도 그 틈에 React 가
+ * `undefined.default` 를 읽어 **오류 화면이 한 번 뜨고 가짜 보고가 남는다.**
+ *
+ * 두 가지를 한다.
+ *  1. **새로고침이 예약돼 있으면 아무것도 결정하지 않는다** — 영영 resolve 하지 않는
+ *     약속을 돌려 Suspense 를 그대로 둔다. 곧 새 판이 뜬다.
+ *  2. 그게 아닌데 모듈이 이상하면 **어느 화면인지 적어** 던진다. 지금까지 이 오류는
+ *     스택이 통째로 vendor-react 안이라(minify 된 `q`) 어느 화면에서 났는지 알 수 없었다.
+ *
+ * Vite 가 아닌 번들러(Next 등)에서는 `vite:preloadError` 가 오지 않으니 이 감싸개는
+ * "모듈이 이상하면 어느 화면인지 적어 던진다" 만 한다 — 그것만으로도 맨 `lazy` 보다 낫다.
+ * @public
+ */
+export declare function lazyPage<T extends ComponentType<any>>(name: string, load: () => Promise<{
+    default: T;
+} | undefined>): LazyExoticComponent<T>;
+
 declare type LeaderboardFn = (gameKey: string, limit?: number) => Promise<LeaderboardRow[] | null>;
 
 /**
@@ -5024,6 +5053,44 @@ export declare interface Recommendation {
  */
 export declare function recommendTables(tables: readonly TableCandidate[], weakLabels: readonly string[], limit?: number): Recommendation[];
 
+/**
+ * 배포 skew 복구 — 그리고 그 복구가 내던 오류 화면.
+ *
+ * ── 무엇이 문제였나 ──
+ * 새 배포로 청크 해시가 바뀌면 캐시된 옛 index.html 이 사라진 청크를 부른다. Vite 는
+ * `vite:preloadError` 를 던지고, 우리는 그때 한 번 새로고침해 새 index.html 을 받는다.
+ * 여기까지는 뜻대로 돈다.
+ *
+ * 그런데 그 이벤트를 `preventDefault()` 하면 Vite 헬퍼가 이렇게 한다(vite 소스 그대로):
+ *
+ *     function handlePreloadError(err) {
+ *       const e = new Event('vite:preloadError', { cancelable: true })
+ *       window.dispatchEvent(e)
+ *       if (!e.defaultPrevented) throw err      // ← 막으면 안 던진다
+ *     }
+ *     return baseModule().catch(handlePreloadError)   // ← 안 던지니 undefined 로 resolve
+ *
+ * **`location.reload()` 는 곧바로 멈추지 않는다.** 새 판이 뜨기 전까지 React 는 계속
+ * 그리고, `React.lazy` 는 resolve 된 `undefined` 의 `.default` 를 읽는다 —
+ * `Cannot read properties of undefined (reading 'default')`. 운영에서 이 오류가
+ * 07-09 ~ 08-28 동안 **아홉 사람에게 열세 번** 났다(/today·/customers·/my-word-table·
+ * /word-pairs·/word-management·/training-store — 스택은 전부 vendor-react 의 lazy 초기화).
+ *
+ * 즉 복구는 되는데 그 길목에서 **오류 화면을 한 번 띄우고 가짜 보고를 남기고** 있었다.
+ *
+ * ── 어떻게 고치나 ──
+ * 새로고침을 걸어 둔 동안에는 `lazy` 가 아무것도 결정하지 않게 한다(`lazyPage` 가
+ * 영영 resolve 하지 않는 약속을 돌려 Suspense 를 그대로 둔다). 그러려면 "지금 새로고침이
+ * 예약돼 있나"를 물을 수 있어야 해서, 그 판단을 여기 한 곳에 둔다.
+ */
+/**
+ * 배포 skew 로 판단되면 1회만 새로고침해 새 index.html 을 받는다.
+ * 앱이 `vite:preloadError`(또는 청크 로드 실패)를 받았을 때 부른다.
+ * @returns 새로고침을 걸었으면 true. 이미 최근에 걸었으면 false(진짜 오류로 넘긴다).
+ * @public
+ */
+export declare function recoverFromSkew(now?: number): boolean;
+
 /** getBoundingClientRect()만 있으면 되는 최소 인터페이스(주로 이벤트의 currentTarget). */
 declare type Rectable = {
     getBoundingClientRect(): DOMRect;
@@ -5341,7 +5408,7 @@ export declare function reviewTableName(original: string | ReviewSource, today:
  * 미지정 시에는 헤더 없는 순수 링만 렌더된다(크기/색상 데모 등).
  * @public
  */
-export declare function RingChart({ titleKey, headRight, icon, showTotal, totalLabelKey, legend, loading, className, inGrid, onClick, ariaLabel, ...ringProps }: RingChartProps): JSX.Element;
+export declare function RingChart({ titleKey, headRight, icon, showTotal, totalLabelKey, legend, loading, className, inGrid, onClick, ariaLabel, tooltip, ...ringProps }: RingChartProps): JSX.Element;
 
 /** @public */
 export declare interface RingChartProps {
@@ -5398,6 +5465,8 @@ export declare interface RingChartProps {
     onClick?: () => void;
     /** 누르는 카드의 이름(낭독기) — 안 주면 제목 */
     ariaLabel?: string;
+    /** 카드에 포인터가 닿을 때(키보드는 초점) 뜨는 설명 — StatChart tooltip 과 같은 뜻(titleKey 지정 시에만) */
+    tooltip?: string;
 }
 
 /** @public */
@@ -5868,6 +5937,15 @@ export declare interface SideNavProps {
     onAppModeChange?: (mode: 'malgwi' | 'manager') => void;
 }
 
+/**
+ * 새로고침을 걸어 두었고 아직 새 판이 안 떴는가.
+ * @public
+ *
+ * `location.reload()` 가 비동기라 그 사이에 React 가 계속 도는데, 그동안 화면에
+ * 무엇을 그릴지 정하는 데 쓴다 — **아무것도 안 그리는 것이 맞다.** 곧 판이 바뀐다.
+ */
+export declare function skewReloadPending(now?: number): boolean;
+
 /**
  * 가로/세로 슬라이더. 접근성·키보드 지원을 위해 input[type=range] 기반.
  * 채워진 부분은 --slider-pct CSS 변수로 그라데이션 처리한다.

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

@@ -13,4 +13,4 @@ import type { BarChartProps } from './barChartTypes';
  *  - 주(week):  'YYYY년 M월 N째주' 드롭다운 + 그 주의 요일(월~일) 막대
  * 원시 렌더링은 내부 BarChartCanvas가 담당한다.
  */
-export default function BarChart({ size, barWidth, titleKey, data, colorA, colorB, labelAKey, labelBKey, showTotal, totalUnitKey, totalLabelKey, control: controlProp, hideControls, rate, rateAgg, tightMax, avgMode, totalFormat, series, seriesMode, loading, onDetail, headExtra, headSegment, icon, disc, onClick, cardAriaLabel, detailSize, barGap, baseline, className, inGrid, }: BarChartProps): import("react").JSX.Element;
+export default function BarChart({ size, barWidth, titleKey, data, colorA, colorB, labelAKey, labelBKey, showTotal, totalUnitKey, totalLabelKey, control: controlProp, hideControls, rate, rateAgg, tightMax, avgMode, totalFormat, series, seriesMode, loading, onDetail, headExtra, headSegment, icon, disc, onClick, cardAriaLabel, cardTooltip, detailSize, barGap, baseline, className, inGrid, }: BarChartProps): import("react").JSX.Element;

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

@@ -261,7 +261,7 @@ const BAR_SIZE_PRESET = {
  *  - 주(week):  'YYYY년 M월 N째주' 드롭다운 + 그 주의 요일(월~일) 막대
  * 원시 렌더링은 내부 BarChartCanvas가 담당한다.
  */
-export default function BarChart({ size = 'medium', barWidth, titleKey, data, colorA, colorB, labelAKey, labelBKey, showTotal = false, totalUnitKey, totalLabelKey, control: controlProp, hideControls = false, rate = false, rateAgg = 'dayMean', tightMax = false, avgMode = false, totalFormat, series, seriesMode = 'stack', loading = false, onDetail, headExtra, headSegment, icon, disc, onClick, cardAriaLabel, detailSize = 32, barGap, baseline, className, inGrid = false, }) {
+export default function BarChart({ size = 'medium', barWidth, titleKey, data, colorA, colorB, labelAKey, labelBKey, showTotal = false, totalUnitKey, totalLabelKey, control: controlProp, hideControls = false, rate = false, rateAgg = 'dayMean', tightMax = false, avgMode = false, totalFormat, series, seriesMode = 'stack', loading = false, onDetail, headExtra, headSegment, icon, disc, onClick, cardAriaLabel, cardTooltip, detailSize = 32, barGap, baseline, className, inGrid = false, }) {
     const { t, i18n } = useTranslation();
     const sizePreset = BAR_SIZE_PRESET[size];
     // 외부 control 미지정 시 내부 컨트롤 사용 (단독 차트 하위 호환)
@@ -397,7 +397,7 @@ export default function BarChart({ size = 'medium', barWidth, titleKey, data, co
     const isLarge = size === 'large';
     const sectionClassName = [isSmall ? 'manager-section--compact' : isLarge ? 'manager-section--full' : undefined, className]
         .filter(Boolean).join(' ') || undefined;
-    return (_jsx(ChartSection, { className: sectionClassName, inGrid: inGrid, icon: icon, disc: disc, onClick: onClick, ariaLabel: cardAriaLabel, headSegment: headSegment, 
+    return (_jsx(ChartSection, { className: sectionClassName, inGrid: inGrid, icon: icon, disc: disc, onClick: onClick, ariaLabel: cardAriaLabel, tooltip: cardTooltip, headSegment: headSegment, 
         /* 좁아 고르개가 '⋯' 로 접히면 상세보기도 그 메뉴로 들어간다 — 머리에 단추 둘이 남지 않게 */
         headMenuItems: onDetail ? [{ label: t('trainingStatus.detail', '상세보기'), icon: 'list', onClick: onDetail, closeOnSelect: true }] : undefined, title: t(titleKey), titleClassName: isSmall ? 'h5 chart-section-title--small' : undefined, headRight: isSmall ? (headExtra ?? undefined) : ({ collapsed }) => _jsxs(_Fragment, { children: [!hideControls && _jsx(BarChartControls, { control: control }), headExtra, onDetail && !collapsed && (_jsx("span", { className: "manager-bar-chart-detail-btn", children: _jsx(Button, { htmlType: "button", size: detailSize, type: "dot", icon: "list", ariaLabel: t('trainingStatus.detail', '상세보기'), showTooltipInfo: t('trainingStatus.detail', '상세보기'), onClick: onDetail }) }))] }), subRow: _jsxs(_Fragment, { children: [showTotal ? ((rate || avgMode || (!!totalLabelKey && !!totalFormat)) ? (
                 // 진행률/평균 모드 또는 totalLabelKey+totalFormat 조합: 라벨(윗줄) + 값(아랫줄). size='small'은 라벨 생략

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

@@ -61,6 +61,9 @@ export interface ChartSectionProps {
     onClick?: () => void;
     /** 누르는 카드의 이름(낭독기) — 안 주면 제목이 글자일 때 그것을 쓴다 */
     ariaLabel?: string;
+    /** 카드에 포인터가 닿을 때(키보드는 초점이 들어올 때) 뜨는 설명 — `StatChart tooltip` 과 같은 뜻.
+     *  같은 줄에 선 StatChart 카드들만 설명이 뜨고 이 카드만 안 뜨던 것을 메운다. */
+    tooltip?: string;
     /** 총계(ChartTotal) + 범례(ChartLegend)를 담는 서브로우 */
     subRow?: ReactNode;
     /** 섹션 루트에 추가할 클래스 */
@@ -80,4 +83,4 @@ export interface ChartSectionProps {
  * 공유하도록 두 컴포넌트가 내부적으로 사용한다.
  * @public
  */
-export default function ChartSection({ title, titleClassName, icon, disc, headRight, headSegment, headMenuItems, collapseBelow, onClick, ariaLabel, subRow, className, inGrid, children }: ChartSectionProps): import("react").JSX.Element;
+export default function ChartSection({ title, titleClassName, icon, disc, headRight, headSegment, headMenuItems, collapseBelow, onClick, ariaLabel, tooltip, subRow, className, inGrid, children }: ChartSectionProps): import("react").JSX.Element;

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

@@ -7,6 +7,8 @@ import Icon from './Icon';
 import Button from './Button';
 import SegmentedControl from './SegmentedControl';
 import Tooltip from './Tooltip/Tooltip';
+import TooltipInfo from './Tooltip/InfoTooltip';
+import { useHoverAnchor } from '../hooks/useHoverAnchor';
 import MenuTooltip from './Tooltip/MenuTooltip';
 /** 차트 범례 — 색상 점 + 라벨 목록. BarChart/RingChart 섹션이 공유. @public */
 export function ChartLegend({ items, className }) {
@@ -25,9 +27,14 @@ export function ChartTotal({ label, children }) {
  * 공유하도록 두 컴포넌트가 내부적으로 사용한다.
  * @public
  */
-export default function ChartSection({ title, titleClassName = 'h3', icon, disc, headRight, headSegment, headMenuItems, collapseBelow = 420, onClick, ariaLabel, subRow, className, inGrid = false, children }) {
+export default function ChartSection({ title, titleClassName = 'h3', icon, disc, headRight, headSegment, headMenuItems, collapseBelow = 420, onClick, ariaLabel, tooltip, subRow, className, inGrid = false, children }) {
     const { t } = useTranslation();
     const secRef = useRef(null);
+    /* 설명 툴팁 — StatChart 와 같은 결(카드 사각형 기준, 포인터가 나가거나 초점이 빠지면 닫힘).
+       hover 전용이면 키보드로는 볼 수 없어 초점에도 연다. */
+    const { anchorRect: 설명자리, openAt: 설명열기, close: 설명닫기 } = useHoverAnchor();
+    const 설명보이기 = useCallback(() => { if (tooltip && secRef.current)
+        설명열기(secRef.current); }, [tooltip, 설명열기]);
     /* 좁은지는 **카드 제 폭** 으로 잰다 — 부르는 쪽이 격자 칸 폭으로 대신 재면 두 칸을 차지하는 카드에서 틀린다.
        ResizeObserver 가 없는 환경(구형·SSR)에서는 접지 않는다(넓은 쪽이 기본). */
     const [좁음, set좁음] = useState(false);
@@ -87,5 +94,12 @@ 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;
-    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, role: onClick ? 'button' : undefined, tabIndex: onClick ? 0 : undefined, "aria-label": onClick ? (ariaLabel ?? (typeof title === 'string' ? title : undefined)) : undefined, children: [_jsxs("div", { className: "manager-section__head", children: [_jsxs("div", { className: "manager-section__title-row", children: [icon && _jsx(Icon, { icon: icon, label: typeof title === 'string' ? title : undefined, className: "manager-section__icon" }), _jsx("div", { className: ['manager-section__title', titleClassName].filter(Boolean).join(' '), children: title })] }), 머리오른쪽, disc && _jsx("div", { className: "manager-section__disc body-3", children: disc })] }), subRow && _jsx("div", { className: "barchart-sub-row", children: subRow }), children, 메뉴자리 && (_jsx(Tooltip, { anchorRect: 메뉴자리, onClose: 메뉴닫기, ariaLabel: headSegment?.ariaLabel ?? t('tooltip.menu', '메뉴'), children: _jsx(MenuTooltip, { columns: [{ items: 메뉴항목 }], onClose: 메뉴닫기, size: "small" }) }))] }));
+    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,
+                    right: 설명자리.right,
+                    bottom: 설명자리.bottom,
+                    width: 설명자리.width,
+                    height: 설명자리.height,
+                }, text: tooltip })), _jsxs("div", { className: "manager-section__head", children: [_jsxs("div", { className: "manager-section__title-row", children: [icon && _jsx(Icon, { icon: icon, label: typeof title === 'string' ? title : undefined, className: "manager-section__icon" }), _jsx("div", { className: ['manager-section__title', titleClassName].filter(Boolean).join(' '), children: title })] }), 머리오른쪽, disc && _jsx("div", { className: "manager-section__disc body-3", children: disc })] }), subRow && _jsx("div", { className: "barchart-sub-row", children: subRow }), children, 메뉴자리 && (_jsx(Tooltip, { anchorRect: 메뉴자리, onClose: 메뉴닫기, ariaLabel: headSegment?.ariaLabel ?? t('tooltip.menu', '메뉴'), children: _jsx(MenuTooltip, { columns: [{ items: 메뉴항목 }], onClose: 메뉴닫기, size: "small" }) }))] }));
 }

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

@@ -64,6 +64,8 @@ export interface RingChartProps {
     onClick?: () => void;
     /** 누르는 카드의 이름(낭독기) — 안 주면 제목 */
     ariaLabel?: string;
+    /** 카드에 포인터가 닿을 때(키보드는 초점) 뜨는 설명 — StatChart tooltip 과 같은 뜻(titleKey 지정 시에만) */
+    tooltip?: string;
 }
 /**
  * 도넛 링 차트 — 전체 대비 완료 비율을 원형 호로 표현.
@@ -71,4 +73,4 @@ export interface RingChartProps {
  * 미지정 시에는 헤더 없는 순수 링만 렌더된다(크기/색상 데모 등).
  * @public
  */
-export default function RingChart({ titleKey, headRight, icon, showTotal, totalLabelKey, legend, loading, className, inGrid, onClick, ariaLabel, ...ringProps }: RingChartProps): import("react").JSX.Element;
+export default function RingChart({ titleKey, headRight, icon, showTotal, totalLabelKey, legend, loading, className, inGrid, onClick, ariaLabel, tooltip, ...ringProps }: RingChartProps): import("react").JSX.Element;

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

@@ -51,7 +51,7 @@ function RingChartCanvas({ done, total, segments, color = 'var(--color-main)', s
  * 미지정 시에는 헤더 없는 순수 링만 렌더된다(크기/색상 데모 등).
  * @public
  */
-export default function RingChart({ titleKey, headRight, icon, showTotal, totalLabelKey, legend, loading, className, inGrid = false, onClick, ariaLabel, ...ringProps }) {
+export default function RingChart({ titleKey, headRight, icon, showTotal, totalLabelKey, legend, loading, className, inGrid = false, onClick, ariaLabel, tooltip, ...ringProps }) {
     const { t } = useTranslation();
     if (!titleKey)
         return _jsx(RingChartCanvas, { ...ringProps });
@@ -64,5 +64,5 @@ export default function RingChart({ titleKey, headRight, icon, showTotal, totalL
         .filter(Boolean).join(' ') || undefined;
     // StatChart(.manager-stat-card__icon)와 동일한 톤 — headRight 자리에 렌더(둘 중 하나만 사용)
     const iconNode = icon && (_jsx("span", { className: "chart-section-icon", children: _jsx(Icon, { icon: icon, className: "chart-section-icon-inner" }) }));
-    return (_jsx(ChartSection, { className: sectionClassName, inGrid: inGrid, onClick: onClick, ariaLabel: ariaLabel, title: t(titleKey), titleClassName: isSmall ? 'h5 chart-section-title--small' : undefined, headRight: iconNode || (isSmall ? undefined : headRight), subRow: (showTotal || legend) && _jsxs(_Fragment, { children: [showTotal ? (_jsxs(ChartTotal, { label: !isSmall && totalLabelKey ? t(totalLabelKey) : undefined, children: [_jsx("span", { className: "barchart-total__num h0", children: pct }), _jsx("span", { className: "barchart-total__unit h5", children: "%" })] })) : _jsx("span", {}), legend && _jsx(ChartLegend, { items: legend })] }), children: loading ? (_jsx("div", { className: "manager-bar-chart-loading", children: _jsx(Loader, { size: 32 }) })) : (_jsx("div", { className: "ring-chart-section-body ring-chart-section-body--offset", children: _jsx(RingChartCanvas, { ...ringProps, hideCenter: ringProps.hideCenter ?? isSmall }) })) }));
+    return (_jsx(ChartSection, { className: sectionClassName, inGrid: inGrid, onClick: onClick, ariaLabel: ariaLabel, tooltip: tooltip, title: t(titleKey), titleClassName: isSmall ? 'h5 chart-section-title--small' : undefined, headRight: iconNode || (isSmall ? undefined : headRight), subRow: (showTotal || legend) && _jsxs(_Fragment, { children: [showTotal ? (_jsxs(ChartTotal, { label: !isSmall && totalLabelKey ? t(totalLabelKey) : undefined, children: [_jsx("span", { className: "barchart-total__num h0", children: pct }), _jsx("span", { className: "barchart-total__unit h5", children: "%" })] })) : _jsx("span", {}), legend && _jsx(ChartLegend, { items: legend })] }), children: loading ? (_jsx("div", { className: "manager-bar-chart-loading", children: _jsx(Loader, { size: 32 }) })) : (_jsx("div", { className: "ring-chart-section-body ring-chart-section-body--offset", children: _jsx(RingChartCanvas, { ...ringProps, hideCenter: ringProps.hideCenter ?? isSmall }) })) }));
 }

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

@@ -103,6 +103,8 @@ export interface BarChartProps {
     onClick?: () => void;
     /** 누르는 카드의 이름(낭독기) — 안 주면 제목 */
     cardAriaLabel?: string;
+    /** 카드에 포인터가 닿을 때(키보드는 초점) 뜨는 설명 — StatChart tooltip 과 같은 뜻 */
+    cardTooltip?: string;
     /** 제목 왼쪽 아이콘 — Section·ChartSection 과 같은 자리·같은 색 */
     icon?: string;
     /** 제목 아래 설명 한 줄 */

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

@@ -0,0 +1,45 @@
+/**
+ * 배포 skew 복구 — 그리고 그 복구가 내던 오류 화면.
+ *
+ * ── 무엇이 문제였나 ──
+ * 새 배포로 청크 해시가 바뀌면 캐시된 옛 index.html 이 사라진 청크를 부른다. Vite 는
+ * `vite:preloadError` 를 던지고, 우리는 그때 한 번 새로고침해 새 index.html 을 받는다.
+ * 여기까지는 뜻대로 돈다.
+ *
+ * 그런데 그 이벤트를 `preventDefault()` 하면 Vite 헬퍼가 이렇게 한다(vite 소스 그대로):
+ *
+ *     function handlePreloadError(err) {
+ *       const e = new Event('vite:preloadError', { cancelable: true })
+ *       window.dispatchEvent(e)
+ *       if (!e.defaultPrevented) throw err      // ← 막으면 안 던진다
+ *     }
+ *     return baseModule().catch(handlePreloadError)   // ← 안 던지니 undefined 로 resolve
+ *
+ * **`location.reload()` 는 곧바로 멈추지 않는다.** 새 판이 뜨기 전까지 React 는 계속
+ * 그리고, `React.lazy` 는 resolve 된 `undefined` 의 `.default` 를 읽는다 —
+ * `Cannot read properties of undefined (reading 'default')`. 운영에서 이 오류가
+ * 07-09 ~ 08-28 동안 **아홉 사람에게 열세 번** 났다(/today·/customers·/my-word-table·
+ * /word-pairs·/word-management·/training-store — 스택은 전부 vendor-react 의 lazy 초기화).
+ *
+ * 즉 복구는 되는데 그 길목에서 **오류 화면을 한 번 띄우고 가짜 보고를 남기고** 있었다.
+ *
+ * ── 어떻게 고치나 ──
+ * 새로고침을 걸어 둔 동안에는 `lazy` 가 아무것도 결정하지 않게 한다(`lazyPage` 가
+ * 영영 resolve 하지 않는 약속을 돌려 Suspense 를 그대로 둔다). 그러려면 "지금 새로고침이
+ * 예약돼 있나"를 물을 수 있어야 해서, 그 판단을 여기 한 곳에 둔다.
+ */
+/**
+ * 배포 skew 로 판단되면 1회만 새로고침해 새 index.html 을 받는다.
+ * 앱이 `vite:preloadError`(또는 청크 로드 실패)를 받았을 때 부른다.
+ * @returns 새로고침을 걸었으면 true. 이미 최근에 걸었으면 false(진짜 오류로 넘긴다).
+ * @public
+ */
+export declare function recoverFromSkew(now?: number): boolean;
+/**
+ * 새로고침을 걸어 두었고 아직 새 판이 안 떴는가.
+ * @public
+ *
+ * `location.reload()` 가 비동기라 그 사이에 React 가 계속 도는데, 그동안 화면에
+ * 무엇을 그릴지 정하는 데 쓴다 — **아무것도 안 그리는 것이 맞다.** 곧 판이 바뀐다.
+ */
+export declare function skewReloadPending(now?: number): boolean;

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

@@ -0,0 +1,70 @@
+/**
+ * 배포 skew 복구 — 그리고 그 복구가 내던 오류 화면.
+ *
+ * ── 무엇이 문제였나 ──
+ * 새 배포로 청크 해시가 바뀌면 캐시된 옛 index.html 이 사라진 청크를 부른다. Vite 는
+ * `vite:preloadError` 를 던지고, 우리는 그때 한 번 새로고침해 새 index.html 을 받는다.
+ * 여기까지는 뜻대로 돈다.
+ *
+ * 그런데 그 이벤트를 `preventDefault()` 하면 Vite 헬퍼가 이렇게 한다(vite 소스 그대로):
+ *
+ *     function handlePreloadError(err) {
+ *       const e = new Event('vite:preloadError', { cancelable: true })
+ *       window.dispatchEvent(e)
+ *       if (!e.defaultPrevented) throw err      // ← 막으면 안 던진다
+ *     }
+ *     return baseModule().catch(handlePreloadError)   // ← 안 던지니 undefined 로 resolve
+ *
+ * **`location.reload()` 는 곧바로 멈추지 않는다.** 새 판이 뜨기 전까지 React 는 계속
+ * 그리고, `React.lazy` 는 resolve 된 `undefined` 의 `.default` 를 읽는다 —
+ * `Cannot read properties of undefined (reading 'default')`. 운영에서 이 오류가
+ * 07-09 ~ 08-28 동안 **아홉 사람에게 열세 번** 났다(/today·/customers·/my-word-table·
+ * /word-pairs·/word-management·/training-store — 스택은 전부 vendor-react 의 lazy 초기화).
+ *
+ * 즉 복구는 되는데 그 길목에서 **오류 화면을 한 번 띄우고 가짜 보고를 남기고** 있었다.
+ *
+ * ── 어떻게 고치나 ──
+ * 새로고침을 걸어 둔 동안에는 `lazy` 가 아무것도 결정하지 않게 한다(`lazyPage` 가
+ * 영영 resolve 하지 않는 약속을 돌려 Suspense 를 그대로 둔다). 그러려면 "지금 새로고침이
+ * 예약돼 있나"를 물을 수 있어야 해서, 그 판단을 여기 한 곳에 둔다.
+ */
+const SKEW_KEY = 'chunk-reload-ts';
+/** 이 시간 안에 다시 실패하면 배포 skew 가 아니라 진짜 오류로 본다(무한 새로고침 방지). */
+const COOLDOWN_MS = 10_000;
+function 마지막시각() {
+    try {
+        return Number(sessionStorage.getItem(SKEW_KEY) || 0);
+    }
+    catch {
+        /* 사생활 보호 모드 등에서 sessionStorage 가 막힌다. 못 읽으면 '없음' 으로 본다 —
+           그러면 새로고침을 한 번 더 하게 될 뿐, 화면이 멈추지는 않는다. */
+        return 0;
+    }
+}
+/**
+ * 배포 skew 로 판단되면 1회만 새로고침해 새 index.html 을 받는다.
+ * 앱이 `vite:preloadError`(또는 청크 로드 실패)를 받았을 때 부른다.
+ * @returns 새로고침을 걸었으면 true. 이미 최근에 걸었으면 false(진짜 오류로 넘긴다).
+ * @public
+ */
+export function recoverFromSkew(now = Date.now()) {
+    if (now - 마지막시각() <= COOLDOWN_MS)
+        return false;
+    try {
+        sessionStorage.setItem(SKEW_KEY, String(now));
+    }
+    catch { /* 못 써도 새로고침은 한다 */ }
+    window.location.reload();
+    return true;
+}
+/**
+ * 새로고침을 걸어 두었고 아직 새 판이 안 떴는가.
+ * @public
+ *
+ * `location.reload()` 가 비동기라 그 사이에 React 가 계속 도는데, 그동안 화면에
+ * 무엇을 그릴지 정하는 데 쓴다 — **아무것도 안 그리는 것이 맞다.** 곧 판이 바뀐다.
+ */
+export function skewReloadPending(now = Date.now()) {
+    const last = 마지막시각();
+    return last > 0 && now - last <= COOLDOWN_MS;
+}

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

@@ -0,0 +1,23 @@
+import { type ComponentType, type LazyExoticComponent } from 'react';
+/**
+ * 화면을 늦게 받아 오는 자리 — `lazy()` 를 그냥 쓰지 않고 이걸 쓴다.
+ *
+ * 맨 `lazy(() => import(…))` 는 **모듈이 undefined 로 와도 그대로 `.default` 를 읽는다.**
+ * 그 일이 실제로 난다: 배포 skew 복구가 `vite:preloadError` 를 `preventDefault()` 하면
+ * Vite 헬퍼의 `catch` 가 아무것도 안 던지고 undefined 로 resolve 한다(자세한 것은
+ * `chunkSkew.ts`). 그러면 새로고침이 이미 걸려 있는데도 그 틈에 React 가
+ * `undefined.default` 를 읽어 **오류 화면이 한 번 뜨고 가짜 보고가 남는다.**
+ *
+ * 두 가지를 한다.
+ *  1. **새로고침이 예약돼 있으면 아무것도 결정하지 않는다** — 영영 resolve 하지 않는
+ *     약속을 돌려 Suspense 를 그대로 둔다. 곧 새 판이 뜬다.
+ *  2. 그게 아닌데 모듈이 이상하면 **어느 화면인지 적어** 던진다. 지금까지 이 오류는
+ *     스택이 통째로 vendor-react 안이라(minify 된 `q`) 어느 화면에서 났는지 알 수 없었다.
+ *
+ * Vite 가 아닌 번들러(Next 등)에서는 `vite:preloadError` 가 오지 않으니 이 감싸개는
+ * "모듈이 이상하면 어느 화면인지 적어 던진다" 만 한다 — 그것만으로도 맨 `lazy` 보다 낫다.
+ * @public
+ */
+export declare function lazyPage<T extends ComponentType<any>>(name: string, load: () => Promise<{
+    default: T;
+} | undefined>): LazyExoticComponent<T>;

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

@@ -0,0 +1,45 @@
+import { lazy } from 'react';
+import { skewReloadPending } from './chunkSkew';
+/**
+ * 화면을 늦게 받아 오는 자리 — `lazy()` 를 그냥 쓰지 않고 이걸 쓴다.
+ *
+ * 맨 `lazy(() => import(…))` 는 **모듈이 undefined 로 와도 그대로 `.default` 를 읽는다.**
+ * 그 일이 실제로 난다: 배포 skew 복구가 `vite:preloadError` 를 `preventDefault()` 하면
+ * Vite 헬퍼의 `catch` 가 아무것도 안 던지고 undefined 로 resolve 한다(자세한 것은
+ * `chunkSkew.ts`). 그러면 새로고침이 이미 걸려 있는데도 그 틈에 React 가
+ * `undefined.default` 를 읽어 **오류 화면이 한 번 뜨고 가짜 보고가 남는다.**
+ *
+ * 두 가지를 한다.
+ *  1. **새로고침이 예약돼 있으면 아무것도 결정하지 않는다** — 영영 resolve 하지 않는
+ *     약속을 돌려 Suspense 를 그대로 둔다. 곧 새 판이 뜬다.
+ *  2. 그게 아닌데 모듈이 이상하면 **어느 화면인지 적어** 던진다. 지금까지 이 오류는
+ *     스택이 통째로 vendor-react 안이라(minify 된 `q`) 어느 화면에서 났는지 알 수 없었다.
+ *
+ * Vite 가 아닌 번들러(Next 등)에서는 `vite:preloadError` 가 오지 않으니 이 감싸개는
+ * "모듈이 이상하면 어느 화면인지 적어 던진다" 만 한다 — 그것만으로도 맨 `lazy` 보다 낫다.
+ * @public
+ */
+/* 서명은 React 의 `lazy` 를 그대로 따른다 — 화면마다 props 가 달라서, 여기서 좁히면
+   쓰는 쪽이 전부 `Property 'userId' does not exist` 로 막힌다(실제로 그렇게 됐다).
+   React 자신도 같은 이유로 이 자리에 any 를 쓴다(@types/react 의 lazy 서명). */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function lazyPage(name, 
+/* 반환 타입에 undefined 를 적어 둔다 — 실제로 그렇게 온다(아래 참고). 타입이
+   "그럴 리 없다"고 말하면 부르는 쪽이 `.then(m => ({ default: m.X }))` 처럼 모듈을
+   그대로 읽는 코드를 쓰게 되고, 그러면 여기 닿기도 전에 터진다. */
+load) {
+    return lazy(async () => {
+        /* **undefined 로 resolve 될 수 있다.** 타입은 그럴 리 없다고 하지만 실제로 그렇게 온다
+           (배포 skew 복구가 preventDefault 한 뒤). 타입을 믿지 말고 확인한다. */
+        const mod = await load();
+        if (mod && typeof mod === 'object' && 'default' in mod) {
+            return mod;
+        }
+        /* 여기 오는 길은 사실상 하나뿐이다 — 청크를 못 받아 복구가 도는 중. 새 판을
+           기다린다. 영영 resolve 하지 않는 약속을 돌려 React 가 이 경계를 건드리지 않게 한다. */
+        if (skewReloadPending())
+            return new Promise(() => { });
+        throw new Error(`[lazyPage] ${name}: 화면 모듈을 받지 못했습니다(default 내보내기 없음). ` +
+            '배포 직후라면 새로고침으로 풀립니다.');
+    });
+}

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

@@ -55,4 +55,6 @@ export { wordContainsChoseong, wordContainsJungseong, wordContainsJongseong, wor
 export { isSyllablePattern, matchesSyllablePattern, validateSyllableSearchInput, patternToComposition, matchesWordQuery, searchAndRankWords } from './utils/koreanSyllable';
 export { PLAN_FEATURES, PLAN_LIMITS, TIER_RANK, getPlanTier, isManagerTier, type PlanTier, type DataLevel, type PlanFeatures, type PlanLimits, } from './utils/planFeatures';
 export { WORD_SUGGESTION_WEEKLY_QUOTA, WORD_SUGGESTION_ACCOUNT_LIMIT, WORD_SUGGESTION_EXISTING_ERROR, isThisWeekPick, } from './utils/wordSuggestionPolicy';
+export { recoverFromSkew, skewReloadPending } from './utils/chunkSkew';
+export { lazyPage } from './utils/lazyPage';
 export { CORE_VERSION } from './version';

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

@@ -44,4 +44,6 @@ export { PLAN_FEATURES, PLAN_LIMITS, TIER_RANK, getPlanTier, isManagerTier, } fr
    말귀어드민(단어 제안 관리)이 같은 숫자를 봐야 하는데, 한쪽 화면 폴더에 두면
    다른 쪽이 그 폴더 없이는 빌드되지 않는다. 값과 순수 함수뿐이다. */
 export { WORD_SUGGESTION_WEEKLY_QUOTA, WORD_SUGGESTION_ACCOUNT_LIMIT, WORD_SUGGESTION_EXISTING_ERROR, isThisWeekPick, } from './utils/wordSuggestionPolicy';
+export { recoverFromSkew, skewReloadPending } from './utils/chunkSkew';
+export { lazyPage } from './utils/lazyPage';
 export { CORE_VERSION } from './version';

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

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

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

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