@ihabdevteam/core 0.246.0 → 0.248.0

package/dist/ihabdevteam-core.d.ts

@@ -310,7 +310,7 @@ export declare type BadgeType = 'bar' | 'dot';
  *  - 주(week):  'YYYY년 M월 N째주' 드롭다운 + 그 주의 요일(월~일) 막대
  * 원시 렌더링은 내부 BarChartCanvas가 담당한다.
  */
-export declare function BarChart({ focusableBars, 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;
+export declare function BarChart({ focusableBars, size, barWidth, titleKey, titleLevel, 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 {
@@ -376,6 +376,12 @@ export declare interface BarChartProps {
     barWidth?: number;
     /** 섹션 제목 i18n 키 */
     titleKey: string;
+    /** 제목을 머리글 몇 급으로 그릴지 — 그대로 `ChartSection` 에 넘긴다(말귀 요청 (60)③, 2026-10-02).
+     *
+     *  `ChartSection` 은 (51) 에서 급을 열었는데 **막대·링은 그 문을 안 달았다.** 그래서 칸을
+     *  부르는 쪽이 급을 못 정하고 늘 기본 3 이 나갔다 — 대시보드 제목이 `h1` 이면 층이
+     *  h1 → h3 로 한 급 비어 읽힌다. 자세한 뜻은 `ChartSectionProps.titleLevel` 참고. */
+    titleLevel?: ChartSectionProps['titleLevel'];
     /** 구간(월) 키 → 주별/일별 데이터 */
     data: Record<string, MonthBarData>;
     colorA: string;
@@ -1645,7 +1651,7 @@ export declare function copyText(text: string): Promise<boolean>;
  *
  * 값은 손으로 적고 `test/coreVersion.test.ts` 가 package.json 과 어긋나면 운다.
  */
-export declare const CORE_VERSION = "0.246.0";
+export declare const CORE_VERSION = "0.248.0";
 
 /** @public */
 declare const coreDefault: Record<string, unknown>;
@@ -4189,7 +4195,7 @@ export declare interface PairStats {
     total: number;
 }
 
-export declare function Panel({ title, icon, disc, actions, size, minHeight, maxWidth, className, scrollable, scrollbarGutter, compactRows, useBorder, useBg, useRowBorder, labelWidth, form, loading, empty, children }: PanelProps): JSX.Element;
+export declare function Panel({ title, titleLevel, icon, disc, actions, size, minHeight, maxWidth, className, scrollable, scrollbarGutter, compactRows, useBorder, useBg, useRowBorder, labelWidth, form, loading, empty, children }: PanelProps): JSX.Element;
 
 /** @public */
 export declare type PanelElement = HTMLDivElement & {
@@ -4204,6 +4210,14 @@ export declare function PanelGrid({ cols, children }: {
 }): JSX.Element;
 
 declare interface PanelProps {
+    /** 제목을 **머리글 몇 급**으로 그릴지(말귀 요청 (59), 2026-10-02).
+     *
+     *  기본 2 는 전과 같다 — **창 제목이 머리글이 아니던 때**의 값이다. 0.242.0 에서 창
+     *  제목이 `<h2>` 가 되면서, 제목 있는 `Panel` 을 품은 창마다 둘이 **같은 급**으로 서게
+     *  됐다(말귀 실측: 훈련 묶음 추가 창에 창 제목 말고 `h2` 가 둘). 머리글로 훑으면 판이
+     *  창의 아래가 아니라 **옆**으로 읽힌다 — 창 안에서는 3 으로 내린다.
+     *  `0` 이면 머리글을 안 세운다(글자 없는 제목은 0.235.0 부터 애초에 안 선다). */
+    titleLevel?: 0 | 2 | 3 | 4 | 5 | 6;
     title?: ReactNode;
     /**
      * 제목 앞에 서는 lucide 아이콘 이름. Section 의 `icon` 과 같은 자리다.
@@ -4351,7 +4365,12 @@ declare type PanelRowInput = Base & {
     disabled?: boolean;
     type?: 'text' | 'email' | 'password' | 'number' | 'tel' | 'url';
     autoComplete?: string;
-    helperText?: string;
+    /** 칸 아래 안내 한 줄 — `aria-describedby` 로 **칸과 이어진다**(말귀 요청 (60)①, 2026-10-02).
+     *
+     *  `ReactNode` 다 — 앱이 `<span role="status">` 로 감싸 **값에 따라 바뀌는 안내**를
+     *  그 자리에서 알릴 수 있게 한 것이다. `error` 로 보내면 될 일이 아니다: `error` 는
+     *  `aria-invalid` 까지 세워 "틀린 값" 이라고 말하는데, 안내는 틀렸다는 말이 아니다. */
+    helperText?: ReactNode;
     /** 최대 글자 수 — 설정 시 입력 제한 + 박스 안쪽 글자수 카운터 표시 */
     maxLength?: number;
     /** 글자수 카운터 표시 여부 (maxLength 설정 시, 기본 true) */
@@ -6059,7 +6078,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, tooltip, ...ringProps }: RingChartProps): JSX.Element;
+export declare function RingChart({ titleKey, titleLevel, headRight, icon, showTotal, totalLabelKey, legend, loading, className, inGrid, onClick, ariaLabel, tooltip, ...ringProps }: RingChartProps): JSX.Element;
 
 /** @public */
 export declare interface RingChartProps {
@@ -6096,6 +6115,8 @@ export declare interface RingChartProps {
      * 감싼 카드로 렌더. 미지정 시 헤더 없는 순수 링만 렌더(기존 동작과 동일).
      */
     titleKey?: string;
+    /** 제목 머리글 급 — 그대로 `ChartSection` 에 넘긴다(`titleKey` 지정 시에만). `BarChartProps.titleLevel` 과 같은 뜻 */
+    titleLevel?: ChartSectionProps['titleLevel'];
     /** 헤더 우측 영역 — 기간 네비게이션, 상세보기 버튼 등 (titleKey 지정 시에만 사용) */
     headRight?: ReactNode;
     /** 제목 옆 아이콘(옅게 표시, StatChart와 동일한 톤) — 지정 시 headRight 자리에 렌더(titleKey 지정 시에만 사용) */
@@ -7580,6 +7601,12 @@ export declare interface TextFieldProps {
     label?: string;
     /** 화면에 보이는 라벨 없이(placeholder만 쓸 때) 스크린리더용 이름을 지정. label이 있으면 무시됨 */
     ariaLabel?: string;
+    /** **바깥에서 그린 설명**의 id — 이 칸 안의 `helperText`·`error` id 와 **함께** 걸린다(덮지 않는다).
+     *
+     *  `PanelRow` 처럼 감싸는 쪽이 도움말을 제 자리에 그리는 자리가 있다. 전에는 그 글이 칸과
+     *  이어지지 않아, 보이기만 하고 낭독기에는 영 안 갔다(말귀 요청 (60)①, 2026-10-02).
+     *  빈칸 띄움으로 여러 개도 된다 — `aria-describedby` 는 id 목록이다. */
+    ariaDescribedBy?: string;
     /** 필수 항목 표시 (*) */
     required?: boolean;
     /** placeholder 텍스트 */

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({ focusableBars, 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;
+export default function BarChart({ focusableBars, size, barWidth, titleKey, titleLevel, 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

@@ -290,7 +290,7 @@ const BAR_SIZE_PRESET = {
  *  - 주(week):  'YYYY년 M월 N째주' 드롭다운 + 그 주의 요일(월~일) 막대
  * 원시 렌더링은 내부 BarChartCanvas가 담당한다.
  */
-export default function BarChart({ focusableBars, 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, }) {
+export default function BarChart({ focusableBars, size = 'medium', barWidth, titleKey, titleLevel, 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 미지정 시 내부 컨트롤 사용 (단독 차트 하위 호환)
@@ -428,7 +428,7 @@ export default function BarChart({ focusableBars, size = 'medium', barWidth, tit
         .filter(Boolean).join(' ') || undefined;
     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)) ? (
+        headMenuItems: onDetail ? [{ label: t('trainingStatus.detail', '상세보기'), icon: 'list', onClick: onDetail, closeOnSelect: true }] : undefined, title: t(titleKey), titleLevel: titleLevel, 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'은 라벨 생략
                 _jsx(ChartTotal, { label: isSmall ? undefined : `${t(control.period === 'week' ? 'manager.chart.weeklyPrefix' : 'manager.chart.monthlyPrefix')} ${t(totalLabelKey ?? labelAKey)}`, children: totalFormat ? (
                     // 숫자는 h0, 단위(시간/분/초 등)는 h5로 분리

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

@@ -4,14 +4,14 @@ import { useCallback, useMemo, useState, useRef } from 'react';
 import { useTranslation } from 'react-i18next';
 import Icon from './Icon';
 import { formatTimeHM } from '../utils/format';
-import { todayYmdOr } from '../utils/date';
+import { todayYmdOr, formatDateLocale } from '../utils/date';
 import './Calendar.css';
 import { pressable } from '../utils/pressable';
 function daysInMonth(year, month) { return new Date(year, month + 1, 0).getDate(); }
 function firstDayOfMonth(year, month) { return new Date(year, month, 1).getDay(); }
 /** @public */
 export default function Calendar({ visits = [], onVisitClick, onVisitMove, onDayClick, today, }) {
-    const { t } = useTranslation();
+    const { t, i18n } = useTranslation();
     const DOW = useMemo(() => t('calendar.dow', { returnObjects: true }), [t]);
     /* '오늘' 은 KST 의 날 — 방문 날짜가 KST 달력(toKstYmd)이라, 기기 달력으로 열면 해외 기기에서 오늘 방문이 안 보이는 달에 있고
        오늘 표시가 다른 날에 붙었다(해외 기기 공식 지원) */
@@ -61,6 +61,8 @@ export default function Calendar({ visits = [], onVisitClick, onVisitMove, onDay
                         const day = d;
                         const dateKey = fmtDate(day);
                         const dayVisits = visitsByDate[dateKey] ?? [];
+                        /* 낭독기에 나가는 '며칠' — 보는 locale 을 따라 글자꼴만 바뀌고 가리키는 날은 KST 하나다(utils/date 머리글) */
+                        const 날짜말 = formatDateLocale(dateKey, i18n.language);
                         const isDragOver = dragOverDate === dateKey;
                         return (_jsxs("div", { className: `calendar-cell${isToday(day) ? ' today' : ''}${isDragOver ? ' drag-over' : ''}${onDayClick ? ' calendar-cell--clickable' : ''}`, role: onDayClick ? 'button' : undefined, tabIndex: onDayClick ? 0 : undefined, "aria-label": onDayClick ? t('calendar.addOnDate', { date: dateKey }) : undefined, "aria-current": isToday(day) ? 'date' : undefined, onClick: onDayClick ? () => onDayClick(dateKey) : undefined, 
                             /* `<div role="button">` 은 브라우저가 Enter·Space 를 눌림으로 바꿔 주지 않는다 */
@@ -83,13 +85,18 @@ export default function Calendar({ visits = [], onVisitClick, onVisitMove, onDay
                                     dragVisitId.current = null;
                                 }
                                 setDragOverDate(null);
-                            } : undefined, children: [_jsx("div", { className: "calendar-cell__number body-3", children: day }), dayVisits.length > 0 && (_jsxs("span", { className: "calendar-cell__visit-count caption-1", "aria-label": t('calendar.visitCount', { count: dayVisits.length, defaultValue: '방문 {{count}}건' }), children: [_jsx("span", { className: "calendar-cell__visit-dot", "aria-hidden": "true" }), dayVisits.length] })), _jsx("div", { className: "calendar-cell__badges", children: dayVisits.map((v, vi) => (_jsxs("div", { draggable: !!onVisitMove, className: `calendar-visit-badge${v.status === 'noVisit' ? ' calendar-visit-badge--no-visit' : v.status === 'scheduled' ? ' calendar-visit-badge--scheduled' : ''}${onVisitClick ? ' calendar-visit-badge--clickable' : ''}${onVisitMove ? ' calendar-visit-badge--draggable' : ''}`, onDragStart: onVisitMove ? (e) => {
+                            } : undefined, children: [_jsx("div", { className: "calendar-cell__number body-3", children: day }), dayVisits.length > 0 && (_jsxs("span", { className: "calendar-cell__visit-count caption-1", "aria-label": `${날짜말} ${t('calendar.visitCount', { count: dayVisits.length, defaultValue: '방문 {{count}}건' })}`, children: [_jsx("span", { className: "calendar-cell__visit-dot", "aria-hidden": "true" }), dayVisits.length] })), _jsx("div", { className: "calendar-cell__badges", children: dayVisits.map((v, vi) => (_jsxs("div", { draggable: !!onVisitMove, className: `calendar-visit-badge${v.status === 'noVisit' ? ' calendar-visit-badge--no-visit' : v.status === 'scheduled' ? ' calendar-visit-badge--scheduled' : ''}${onVisitClick ? ' calendar-visit-badge--clickable' : ''}${onVisitMove ? ' calendar-visit-badge--draggable' : ''}`, onDragStart: onVisitMove ? (e) => {
                                             dragVisitId.current = v.id;
                                             e.dataTransfer.effectAllowed = 'move';
                                         } : undefined, onDragEnd: onVisitMove ? () => {
                                             dragVisitId.current = null;
                                             setDragOverDate(null);
                                         } : undefined, onClick: onVisitClick ? (e) => { e.stopPropagation(); onVisitClick(v); } : undefined, ...pressable(onVisitClick ? () => onVisitClick(v) : undefined), "aria-label": [
+                                            // **며칠**이 빠져 있었다 — 칸 번호(1~31)는 `aria-hidden` 도 아니지만 이름표의
+                                            // 이름을 대체하므로 낭독기에는 "12시 55분 지한 예약" 만 가고, 어느 날 것인지는
+                                            // 안 간다. 격자 꼴(`gridcell`)로 날을 함께 읽히는 길도 있지만 그건 화살표
+                                            // 이동까지 약속하는 것이라, 지금은 이름 안에 날을 적는다(말귀 요청 (60)②).
+                                            날짜말,
                                             v.time ? formatTimeHM(v.time, t) : null,
                                             v.customer,
                                             t(v.status === 'noVisit' ? 'calendar.legend.noVisit'

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

@@ -2,6 +2,14 @@ import { type ReactNode } from 'react';
 import './Panel.css';
 type PanelSize = 'small' | 'medium' | 'large';
 interface PanelProps {
+    /** 제목을 **머리글 몇 급**으로 그릴지(말귀 요청 (59), 2026-10-02).
+     *
+     *  기본 2 는 전과 같다 — **창 제목이 머리글이 아니던 때**의 값이다. 0.242.0 에서 창
+     *  제목이 `<h2>` 가 되면서, 제목 있는 `Panel` 을 품은 창마다 둘이 **같은 급**으로 서게
+     *  됐다(말귀 실측: 훈련 묶음 추가 창에 창 제목 말고 `h2` 가 둘). 머리글로 훑으면 판이
+     *  창의 아래가 아니라 **옆**으로 읽힌다 — 창 안에서는 3 으로 내린다.
+     *  `0` 이면 머리글을 안 세운다(글자 없는 제목은 0.235.0 부터 애초에 안 선다). */
+    titleLevel?: 0 | 2 | 3 | 4 | 5 | 6;
     title?: ReactNode;
     /**
      * 제목 앞에 서는 lucide 아이콘 이름. Section 의 `icon` 과 같은 자리다.
@@ -54,7 +62,7 @@ interface PanelProps {
     empty?: ReactNode;
     children?: ReactNode;
 }
-export default function Panel({ title, icon, disc, actions, size, minHeight, maxWidth, className, scrollable, scrollbarGutter, compactRows, useBorder, useBg, useRowBorder, labelWidth, form, loading, empty, children }: PanelProps): import("react").JSX.Element;
+export default function Panel({ title, titleLevel, icon, disc, actions, size, minHeight, maxWidth, className, scrollable, scrollbarGutter, compactRows, useBorder, useBg, useRowBorder, labelWidth, form, loading, empty, children }: PanelProps): import("react").JSX.Element;
 /** @public */
 export declare function PanelGrid({ cols, children }: {
     cols?: number;

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

@@ -5,7 +5,7 @@ import { PanelRow } from './PanelRow';
 import { Children } from 'react';
 import Icon from './Icon';
 import './Panel.css';
-export default function Panel({ title, icon, disc, actions, size = 'medium', minHeight, maxWidth, className, scrollable, scrollbarGutter = 'auto', compactRows = false, useBorder = true, useBg = true, useRowBorder = true, labelWidth, form = false, loading, empty, children }) {
+export default function Panel({ title, titleLevel = 2, icon, disc, actions, size = 'medium', minHeight, maxWidth, className, scrollable, scrollbarGutter = 'auto', compactRows = false, useBorder = true, useBg = true, useRowBorder = true, labelWidth, form = false, loading, empty, children }) {
     const cls = cx('panel', `panel--${size}`, form ? 'panel--form' : '', 
     /* minHeight 패널은 마지막 행 아래 빈 공간이 생길 수 있으므로 행 하단 구분선 사용 */
     minHeight !== undefined ? 'panel--fill' : '', !useBorder ? 'panel--no-border' : '', !useBg ? 'panel--no-bg' : '', !useRowBorder ? 'panel--no-row-border' : '', compactRows ? 'panel--compact-rows' : '', className);
@@ -16,7 +16,8 @@ export default function Panel({ title, icon, disc, actions, size = 'medium', min
         style.maxWidth = typeof maxWidth === 'number' ? `${maxWidth}px` : maxWidth;
     if (labelWidth !== undefined)
         style['--panel-label-width'] = typeof labelWidth === 'number' ? `${labelWidth}px` : labelWidth;
-    return (_jsxs("div", { className: cls, style: Object.keys(style).length ? style : undefined, children: [(!!title || disc != null) && (_jsxs("div", { className: cx('panel__header', disc != null ? 'panel__header--with-disc' : ''), children: [icon && (_jsx(Icon, { icon: icon, label: typeof title === 'string' ? title : undefined, className: "panel__icon" })), _jsxs("div", { className: "panel__title-group", children: [!!title && (_jsx("h2", { className: `panel__title ${disc != null ? 'body-3b' : 'h5b'}`, children: title })), disc != null && _jsx("p", { className: "panel__disc caption-1", children: disc })] }), actions && _jsx("div", { className: "panel__actions", children: actions })] })), loading ? (_jsx(PanelRow, { variant: "loading" })
+    const 제목태그 = titleLevel ? `h${titleLevel}` : 'div';
+    return (_jsxs("div", { className: cls, style: Object.keys(style).length ? style : undefined, children: [(!!title || disc != null) && (_jsxs("div", { className: cx('panel__header', disc != null ? 'panel__header--with-disc' : ''), children: [icon && (_jsx(Icon, { icon: icon, label: typeof title === 'string' ? title : undefined, className: "panel__icon" })), _jsxs("div", { className: "panel__title-group", children: [!!title && (_jsx(제목태그, { className: `panel__title ${disc != null ? 'body-3b' : 'h5b'}`, children: title })), disc != null && _jsx("p", { className: "panel__disc caption-1", children: disc })] }), actions && _jsx("div", { className: "panel__actions", children: actions })] })), loading ? (_jsx(PanelRow, { variant: "loading" })
             /* 비었는지는 React 가 그리는 것으로 센다 — `{조건 && 행들}` 이 false 면 children 이 false 라 빈 상태 문구가 안 떴다 */
             ) : empty != null && Children.toArray(children).length === 0 ? (_jsx(PanelRow, { variant: "empty", children: empty })) : scrollable ? (_jsx("div", { className: cx('panel__body--scroll', scrollbarGutter === 'stable' && 'panel__body--gutter-stable'), children: children })) : children] }));
 }

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

@@ -99,7 +99,12 @@ export type PanelRowInput = Base & {
     disabled?: boolean;
     type?: 'text' | 'email' | 'password' | 'number' | 'tel' | 'url';
     autoComplete?: string;
-    helperText?: string;
+    /** 칸 아래 안내 한 줄 — `aria-describedby` 로 **칸과 이어진다**(말귀 요청 (60)①, 2026-10-02).
+     *
+     *  `ReactNode` 다 — 앱이 `<span role="status">` 로 감싸 **값에 따라 바뀌는 안내**를
+     *  그 자리에서 알릴 수 있게 한 것이다. `error` 로 보내면 될 일이 아니다: `error` 는
+     *  `aria-invalid` 까지 세워 "틀린 값" 이라고 말하는데, 안내는 틀렸다는 말이 아니다. */
+    helperText?: ReactNode;
     /** 최대 글자 수 — 설정 시 입력 제한 + 박스 안쪽 글자수 카운터 표시 */
     maxLength?: number;
     /** 글자수 카운터 표시 여부 (maxLength 설정 시, 기본 true) */

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

@@ -74,6 +74,8 @@ export function PanelRow(props) {
     const toggleId = variant === 'toggle' ? `panel-toggle-${uid}` : undefined;
     // 오류 문구 id — 드롭다운 행은 트리거가 이 문구를 설명으로 잇는다(aria-invalid 만으로는 무엇이 틀렸는지 안 들린다)
     const errorId = error ? `panel-error-${uid}` : undefined;
+    /* 도움말은 variant 와 무관하게 한 자리에서 짓는다 — id 는 그릴 때와 걸 때 **같아야** 한다 */
+    const helperId = `panel-helper-${uid}`;
     if (variant === 'toggle') {
         const p = props;
         right = _jsx(Toggle, { checked: p.checked, onChange: p.onChange, id: toggleId });
@@ -111,7 +113,7 @@ export function PanelRow(props) {
     }
     else if (variant === 'input') {
         const p = props;
-        right = (_jsxs("div", { className: `panel-row__input-wrap${useFullWidth ? ' panel-row__input-wrap--full' : ''}`, children: [_jsx(TextField, { value: p.value, onChange: p.onChange ?? noop, onKeyDown: p.onKeyDown, onEnter: p.onEnter, placeholder: p.placeholder, ghostText: p.ghostText, ghostHint: p.ghostHint, inputMode: p.inputMode, readOnly: p.readOnly, disabled: p.disabled, type: p.type, autoComplete: p.autoComplete, maxLength: p.maxLength, showCount: p.showCount, multiline: p.multiline, rows: p.rows, fullWidth: useFullWidth, error: error, ariaLabel: label, required: required }), p.helperText && _jsx("div", { className: "panel-row__helper caption-1", children: p.helperText })] }));
+        right = (_jsxs("div", { className: `panel-row__input-wrap${useFullWidth ? ' panel-row__input-wrap--full' : ''}`, children: [_jsx(TextField, { value: p.value, onChange: p.onChange ?? noop, onKeyDown: p.onKeyDown, onEnter: p.onEnter, placeholder: p.placeholder, ghostText: p.ghostText, ghostHint: p.ghostHint, inputMode: p.inputMode, readOnly: p.readOnly, disabled: p.disabled, type: p.type, autoComplete: p.autoComplete, maxLength: p.maxLength, showCount: p.showCount, multiline: p.multiline, rows: p.rows, fullWidth: useFullWidth, error: error, ariaLabel: label, required: required, ariaDescribedBy: p.helperText ? helperId : undefined }), p.helperText && _jsx("div", { id: helperId, className: "panel-row__helper caption-1", children: p.helperText })] }));
     }
     else if (variant === 'custom') {
         const p = props;

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

@@ -1,6 +1,6 @@
 import './RingChart.css';
 import type { ReactNode } from 'react';
-import type { ChartLegendItem } from './ChartSection';
+import type { ChartLegendItem, ChartSectionProps } from './ChartSection';
 /** 시맨틱 사이즈 → 지름(px)·링 두께(px) 프리셋 */
 export type RingChartSize = 'small' | 'medium' | 'large';
 /** @public */
@@ -44,6 +44,8 @@ export interface RingChartProps {
      * 감싼 카드로 렌더. 미지정 시 헤더 없는 순수 링만 렌더(기존 동작과 동일).
      */
     titleKey?: string;
+    /** 제목 머리글 급 — 그대로 `ChartSection` 에 넘긴다(`titleKey` 지정 시에만). `BarChartProps.titleLevel` 과 같은 뜻 */
+    titleLevel?: ChartSectionProps['titleLevel'];
     /** 헤더 우측 영역 — 기간 네비게이션, 상세보기 버튼 등 (titleKey 지정 시에만 사용) */
     headRight?: ReactNode;
     /** 제목 옆 아이콘(옅게 표시, StatChart와 동일한 톤) — 지정 시 headRight 자리에 렌더(titleKey 지정 시에만 사용) */
@@ -73,4 +75,4 @@ export interface RingChartProps {
  * 미지정 시에는 헤더 없는 순수 링만 렌더된다(크기/색상 데모 등).
  * @public
  */
-export default function RingChart({ titleKey, headRight, icon, showTotal, totalLabelKey, legend, loading, className, inGrid, onClick, ariaLabel, tooltip, ...ringProps }: RingChartProps): import("react").JSX.Element;
+export default function RingChart({ titleKey, titleLevel, 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, tooltip, ...ringProps }) {
+export default function RingChart({ titleKey, titleLevel, headRight, icon, showTotal, totalLabelKey, legend, loading, className, inGrid = false, onClick, ariaLabel, tooltip, ...ringProps }) {
     const { t } = useTranslation();
     if (!titleKey)
         return _jsx(RingChartCanvas, { ...ringProps });
@@ -66,7 +66,7 @@ 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, 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 ? (
+    return (_jsx(ChartSection, { className: sectionClassName, inGrid: inGrid, onClick: onClick, ariaLabel: ariaLabel, tooltip: tooltip, title: t(titleKey), titleLevel: titleLevel, 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 ? (
         /* 링도 같은 병이 있었다 — 기다림 상자 186px, 그려진 링은 지름(medium 120px)이다.
            **그려질 링과 같은 자리·같은 지름**의 뼈대를 세우고 그 안에서 기다린다
            (BarChart 와 같은 결, 사용자 지시 2026-09-17 "뼈대 먼저, 그 안에서 로딩"). */

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

@@ -17,6 +17,12 @@ export interface TextFieldProps {
     label?: string;
     /** 화면에 보이는 라벨 없이(placeholder만 쓸 때) 스크린리더용 이름을 지정. label이 있으면 무시됨 */
     ariaLabel?: string;
+    /** **바깥에서 그린 설명**의 id — 이 칸 안의 `helperText`·`error` id 와 **함께** 걸린다(덮지 않는다).
+     *
+     *  `PanelRow` 처럼 감싸는 쪽이 도움말을 제 자리에 그리는 자리가 있다. 전에는 그 글이 칸과
+     *  이어지지 않아, 보이기만 하고 낭독기에는 영 안 갔다(말귀 요청 (60)①, 2026-10-02).
+     *  빈칸 띄움으로 여러 개도 된다 — `aria-describedby` 는 id 목록이다. */
+    ariaDescribedBy?: string;
     /** 필수 항목 표시 (*) */
     required?: boolean;
     /** placeholder 텍스트 */

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

@@ -13,7 +13,7 @@ import { useIsoLayoutEffect } from '../hooks/useIsoLayoutEffect';
 import './TextField.css';
 /** @public */
 export default function TextField(props) {
-    const { value, defaultValue, name, inputRef, onChange, label, ariaLabel, required, placeholder, ghostText, ghostHint, type = 'text', disabled = false, readOnly = false, error, helperText, maxLength, size = 48, variant = 'input', fullWidth = false, newline = false, multiline = false, rows = 3, leftIcon, rightIcon, clearable = false, list, showCount = true, className = '', onFocus, onBlur, onKeyDown, onEnter, inputMode, autoComplete, autoFocus, suggestions: suggestionsProp, filterSuggestions, onSelectSuggestion, autoActiveFirst, openOnFocus = false, } = props;
+    const { value, defaultValue, name, inputRef, onChange, label, ariaLabel, ariaDescribedBy, required, placeholder, ghostText, ghostHint, type = 'text', disabled = false, readOnly = false, error, helperText, maxLength, size = 48, variant = 'input', fullWidth = false, newline = false, multiline = false, rows = 3, leftIcon, rightIcon, clearable = false, list, showCount = true, className = '', onFocus, onBlur, onKeyDown, onEnter, inputMode, autoComplete, autoFocus, suggestions: suggestionsProp, filterSuggestions, onSelectSuggestion, autoActiveFirst, openOnFocus = false, } = props;
     // 읽기 전용·꺼진 칸은 후보로 값을 바꾸지 못한다 — 전에는 ↓·Enter·후보 누름으로 onChange 가 나갔다
     const suggestions = readOnly || disabled ? undefined : suggestionsProp;
     const { t } = useTranslation();
@@ -164,7 +164,9 @@ export default function TextField(props) {
         'aria-label': !label && ariaLabel ? ariaLabel : undefined,
         'aria-required': required,
         'aria-invalid': !!error,
-        'aria-describedby': (helperText || error) ? helperId : undefined,
+        /* 안의 것(helperText·error)과 바깥의 것(ariaDescribedBy)을 **잇는다** — 둘 중 하나로
+           덮으면 오류가 뜬 순간 바깥 도움말이 사라지거나, 반대로 오류가 안 읽힌다. */
+        'aria-describedby': [(helperText || error) ? helperId : null, ariaDescribedBy].filter(Boolean).join(' ') || undefined,
         // aria-expanded·aria-controls·aria-activedescendant 는 콤보박스 속성이라 role 없이는
         // 스크린리더가 그냥 입력칸으로 읽고 "후보 n개"를 알리지 않는다 — 역할을 함께 준다.
         role: suggestions ? 'combobox' : undefined,

package/dist/packages/core/src/components/Training/CategoryIcon.js

@@ -1,5 +1,6 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useTranslation } from 'react-i18next';
 import { cx } from '../../utils/cx';
 import { useCallback, useRef, useState, useEffect, useLayoutEffect, useMemo } from "react";
 import InfoTooltip from "../Tooltip/InfoTooltip";
@@ -7,6 +8,7 @@ import Icon from '../Icon';
 import "./CategoryIcon.css";
 /** @public */
 export default function CategoryIcon({ icon, label, tooltip, wrapperStyle, color, bgColor, useHover = true, iconSize = 'medium' }) {
+    const { t } = useTranslation();
     const isSmallIcon = iconSize === 'small';
     const cls = cx('category-icon', isSmallIcon ? 'category-icon--small' : '');
     const svgSize = isSmallIcon ? 16 : 20;
@@ -75,5 +77,5 @@ export default function CategoryIcon({ icon, label, tooltip, wrapperStyle, color
             setHover(v => !v);
         }
     }, []);
-    return (_jsxs("span", { ref: ref, className: "category-icon__wrap", onPointerEnter: handleHoverOn, onPointerLeave: handleHoverOff, onFocus: handleHoverOn, onBlur: handleHoverOff, onKeyDown: handleKeyDown, role: "button", tabIndex: 0, "aria-label": typeof tipText === 'string' ? tipText : undefined, "aria-haspopup": !!tipText, "aria-expanded": hover, "data-tooltip-ignore": true, children: [_jsx(Icon, { icon: icon, label: label, className: cls, imgClassName: "category-icon__image", maskClassName: "category-icon__mask", svgClassName: "category-icon__svg", wrapperStyle: resolvedWrapperStyle, size: svgSize }), hover && tipText && (_jsx(InfoTooltip, { anchorRect: anchorRect, text: typeof tipText === 'string' ? tipText : undefined, offset: 8, onClose: handleTooltipClose, className: "category-icon__tooltip", ariaLabel: typeof tipText === 'string' ? tipText : undefined }))] }));
+    return (_jsxs("span", { ref: ref, className: "category-icon__wrap", onPointerEnter: handleHoverOn, onPointerLeave: handleHoverOff, onFocus: handleHoverOn, onBlur: handleHoverOff, onKeyDown: handleKeyDown, role: "button", tabIndex: 0, "aria-label": typeof tipText === 'string' ? t('common.descriptionFor', { name: tipText, defaultValue: `${tipText} 설명` }) : undefined, "aria-haspopup": !!tipText, "aria-expanded": hover, "data-tooltip-ignore": true, children: [_jsx(Icon, { icon: icon, label: label, className: cls, imgClassName: "category-icon__image", maskClassName: "category-icon__mask", svgClassName: "category-icon__svg", wrapperStyle: resolvedWrapperStyle, size: svgSize }), hover && tipText && (_jsx(InfoTooltip, { anchorRect: anchorRect, text: typeof tipText === 'string' ? tipText : undefined, offset: 8, onClose: handleTooltipClose, className: "category-icon__tooltip", ariaLabel: typeof tipText === 'string' ? tipText : undefined }))] }));
 }

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

@@ -1,5 +1,5 @@
 import type { ReactNode } from 'react';
-import type { ChartHeadSegment } from './ChartSection';
+import type { ChartHeadSegment, ChartSectionProps } from './ChartSection';
 import type { MonthBarData } from './barChartData';
 /** @public */
 export interface BarChartControl {
@@ -61,6 +61,12 @@ export interface BarChartProps {
     barWidth?: number;
     /** 섹션 제목 i18n 키 */
     titleKey: string;
+    /** 제목을 머리글 몇 급으로 그릴지 — 그대로 `ChartSection` 에 넘긴다(말귀 요청 (60)③, 2026-10-02).
+     *
+     *  `ChartSection` 은 (51) 에서 급을 열었는데 **막대·링은 그 문을 안 달았다.** 그래서 칸을
+     *  부르는 쪽이 급을 못 정하고 늘 기본 3 이 나갔다 — 대시보드 제목이 `h1` 이면 층이
+     *  h1 → h3 로 한 급 비어 읽힌다. 자세한 뜻은 `ChartSectionProps.titleLevel` 참고. */
+    titleLevel?: ChartSectionProps['titleLevel'];
     /** 구간(월) 키 → 주별/일별 데이터 */
     data: Record<string, MonthBarData>;
     colorA: string;

package/dist/packages/core/src/i18n/locales/en.json

@@ -30,6 +30,7 @@
         "likeCount": "{{count}} likes",
         "selectedOfMax": "{{count}} of {{max}}",
         "downloadCount": "{{count}} downloads",
+        "descriptionFor": "About {{name}}",
         "search": "Search",
         "empty": "No data.",
         "yes": "Yes",

package/dist/packages/core/src/i18n/locales/ko.json

@@ -28,6 +28,7 @@
         "download": "다운로드",
         "likeCount": "좋아요 {{count}}",
         "downloadCount": "가져간 수 {{count}}",
+        "descriptionFor": "{{name}} 설명",
         "search": "검색",
         "empty": "데이터가 없습니다.",
         "yes": "예",

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

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

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

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