@ihabdevteam/core 0.149.0 → 0.151.0

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

@@ -5,6 +5,12 @@ export interface AccordionItem {
     title: ReactNode;
     body: ReactNode;
     avatar?: ReactNode;
+    /**
+     * 항목의 변하지 않는 이름. 주면 펼침 상태가 **자리 번호가 아니라 이 id 에** 묶인다 —
+     * 목록 앞에 항목이 더해지거나 빠져도(새 공지가 맨 위에 붙는 등) 펼친 항목이 그대로 펼쳐져 있다.
+     * 안 주면 지금처럼 자리 번호로 묶인다. 같은 목록 안에서 겹치지 않아야 한다.
+     */
+    id?: string;
 }
 /** @public */
 export interface AccordionProps {

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

@@ -31,6 +31,9 @@ function Item({ title, body, open = false, onToggle, avatar, titleClassName = 'b
 // ── Accordion ─────────────────────────────────────────────────────────────
 /** @public */
 export default function Accordion({ items = [], defaultOpenIndex = 0, size = 72, className = '', bodyClassName, }) {
-    const [openIndex, setOpenIndex] = useState(defaultOpenIndex);
-    return (_jsx("div", { className: `accordion-group accordion-group--s${size} ${className}`.trim(), role: "list", children: items.map((item, i) => (_jsx(Item, { title: item.title, body: item.body, avatar: item.avatar, open: i === openIndex, onToggle: () => setOpenIndex(i === openIndex ? -1 : i), bodyClassName: bodyClassName }, i))) }));
+    /* 펼침을 자리 번호로만 들고 있어, 앞에 항목이 더해지면 **다른 항목이** 펼쳐졌다. id 가 있는 항목을 누르면 id 로 기억한다.
+       처음(아직 누르기 전)은 defaultOpenIndex 자리 — 항목이 늦게 와도 그 자리가 열린다(예전과 같다). */
+    const [열림, set열림] = useState({ index: defaultOpenIndex });
+    const 열렸나 = (item, i) => 열림.id != null && item.id != null ? item.id === 열림.id : 열림.id == null && i === 열림.index;
+    return (_jsx("div", { className: `accordion-group accordion-group--s${size} ${className}`.trim(), role: "list", children: items.map((item, i) => (_jsx(Item, { title: item.title, body: item.body, avatar: item.avatar, open: 열렸나(item, i), onToggle: () => set열림(열렸나(item, i) ? { index: -1 } : { index: i, id: item.id }), bodyClassName: bodyClassName }, item.id ?? i))) }));
 }

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

@@ -12,7 +12,13 @@ export interface AlertProps {
     /** 닫기(×) 버튼 표시 여부 */
     dismissible?: boolean;
     onDismiss?: () => void;
+    /**
+     * 낭독기에 알리는 방식. 안 주면 톤이 정한다 — `danger`·`warning` 은 `'assertive'`(`role="alert"`, 하던 말을 끊고 읽음),
+     * `info`·`success` 는 `'polite'`(`role="status"`, 하던 말 뒤에 읽음).
+     * `'off'` 는 live 역할을 두지 않는다 — 화면에 늘 놓인 안내(설정 화면 머리의 주의 글 등)가 열 때마다 끼어들어 읽히지 않게.
+     */
+    live?: 'assertive' | 'polite' | 'off';
     className?: string;
 }
 /** @public */
-export default function Alert({ tone, title, message, children, dismissible, onDismiss, className, }: AlertProps): import("react").JSX.Element | null;
+export default function Alert({ tone, title, message, children, dismissible, onDismiss, live, className, }: AlertProps): import("react").JSX.Element | null;

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

@@ -1,7 +1,8 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cx } from '../utils/cx';
-import { useCallback, useState } from 'react';
+import { useCallback, useRef, useState } from 'react';
+import { moveFocusOutside } from '../hooks/focusReturn';
 import { useTranslation } from 'react-i18next';
 import Icon from './Icon';
 import './Alert.css';
@@ -12,17 +13,25 @@ const TONE_ICON = {
     danger: 'alert-circle',
 };
 /** @public */
-export default function Alert({ tone = 'info', title, message, children, dismissible = false, onDismiss, className = '', }) {
+export default function Alert({ tone = 'info', title, message, children, dismissible = false, onDismiss, live, className = '', }) {
     const { t } = useTranslation();
     const [dismissed, setDismissed] = useState(false);
+    const rootRef = useRef(null);
     const handleDismiss = useCallback(() => {
+        /* 닫기 단추에 있던 포커스가 상자와 함께 사라져 body 로 떨어졌다 — 떼기 전에 상자 앞의 포커스 받을 곳으로 옮긴다 */
+        const root = rootRef.current;
+        if (root && root.contains(document.activeElement))
+            moveFocusOutside(root);
         setDismissed(true);
         onDismiss?.();
     }, [onDismiss]);
     if (dismissed)
         return null;
     const cls = cx('alert', `alert--${tone}`, className);
+    /* 톤과 상관없이 늘 role="alert" 였다 — "저장했습니다"(success)·안내(info)까지 하던 말을 끊고 읽혔다 */
+    const 방식 = live ?? (tone === 'danger' || tone === 'warning' ? 'assertive' : 'polite');
+    const role = 방식 === 'assertive' ? 'alert' : 방식 === 'polite' ? 'status' : undefined;
     const hasTitle = Boolean(title);
     const hasMessage = Boolean(message || children);
-    return (_jsxs("div", { className: cls, role: "alert", children: [_jsxs("div", { className: "alert__body", children: [_jsxs("div", { className: "alert__header", children: [_jsx(Icon, { icon: TONE_ICON[tone], size: 20, className: "alert__icon" }), hasTitle && _jsx("span", { className: "alert__title body-2", children: title }), !hasTitle && hasMessage && _jsx("div", { className: "alert__message body-3", children: message || children })] }), hasTitle && hasMessage && (_jsx("div", { className: "alert__message alert__message--indented body-3", children: message || children }))] }), dismissible && (_jsx("button", { type: "button", className: "alert__dismiss", onClick: handleDismiss, "aria-label": t('common.close', '닫기'), children: "\u00D7" }))] }));
+    return (_jsxs("div", { ref: rootRef, className: cls, role: role, children: [_jsxs("div", { className: "alert__body", children: [_jsxs("div", { className: "alert__header", children: [_jsx(Icon, { icon: TONE_ICON[tone], size: 20, className: "alert__icon" }), hasTitle && _jsx("span", { className: "alert__title body-2", children: title }), !hasTitle && hasMessage && _jsx("div", { className: "alert__message body-3", children: message || children })] }), hasTitle && hasMessage && (_jsx("div", { className: "alert__message alert__message--indented body-3", children: message || children }))] }), dismissible && (_jsx("button", { type: "button", className: "alert__dismiss", onClick: handleDismiss, "aria-label": t('common.close', '닫기'), children: "\u00D7" }))] }));
 }

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

@@ -30,7 +30,8 @@ function BarChartCanvas({ data, colorA, colorB, labelA, labelB, barWidth = 10, h
     const barsPerCol = stacked ? 1 : (single ? 1 : 2);
     const effBarWidth = useMemo(() => {
         const cols = Math.max(1, data.length);
-        return Math.max(8, Math.min(barWidth, Math.round(120 / (cols * barsPerCol) + 6)));
+        /* 하한 2px — 8 이던 때는 barWidth 6(말귀 훈련 현황의 가는 막대)을 넘겨도 8 로 올라갔다. 자동 축소 식은 6 밑으로 안 내려간다 */
+        return Math.max(2, Math.min(barWidth, Math.round(120 / (cols * barsPerCol) + 6)));
     }, [data.length, barsPerCol, barWidth]);
     /* 굵기는 인라인 flex/maxWidth 가 아니라 CSS 변수로 박는다 — 소비자가 `!important`
        없이 CSS 로 덮을 수 있게. 읽는 규칙은 BarChart.css 의 `.manager-bar-chart-bar`·`-stack`. */
@@ -249,7 +250,11 @@ export default function BarChart({ size = 'medium', barWidth, titleKey, data, co
                 : elapsed.reduce((s, d) => s + (d.a > 0 ? d.a : 0), 0);
             return Math.round(sum / elapsed.length);
         }
-        return bars.reduce((s, d) => s + (d.a > 0 ? d.a : 0) + (labelBKey && d.b > 0 ? d.b : 0), 0);
+        /* 월 보기 합계는 **그 달 날짜만** — 주 막대는 월요일 시작 7일이라 달 경계를 넘는다(마지막 주는 다음 달 날, 첫 월요일 앞 날은
+           앞 달 막대). 막대 합으로 내면 8월 합계에 9/1~9/6 이 들고 8/1~8/2 가 빠져, 상세 목록(달력 달)의 건수와 어긋났다.
+           주 보기는 그 주 막대의 합 그대로. */
+        const 합칠것 = control.period === 'month' ? (data[control.monthRange]?.daily ?? []) : bars;
+        return 합칠것.reduce((s, d) => s + (d.a > 0 ? d.a : 0) + (labelBKey && d.b > 0 ? d.b : 0), 0);
     }, [bars, rawBars, rate, avgMode, labelBKey, control.period, control.monthRange, data]);
     const legendItems = series && series.length > 0
         ? series.map(s => ({ color: s.color, label: s.label }))

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

@@ -23,7 +23,7 @@ export interface BoardProps<T> {
     title?: ReactNode;
     /** 우측 상단 영역 — 검색 입력 등. 상태는 소비자가 소유한다 */
     toolbar?: ReactNode;
-    /** rows가 비었을 때 표시할 내용 */
+    /** rows가 비었을 때 표시할 내용. 기본은 i18n `board.empty`(ko '등록된 항목이 없습니다.') */
     empty?: ReactNode;
     /** 로딩 중 표시할 내용 — 지정 시 rows 대신 렌더 */
     loading?: ReactNode;
@@ -33,7 +33,10 @@ export interface BoardProps<T> {
 }
 /**
  * 게시판형 목록 표. 상태를 갖지 않는 표현 컴포넌트이므로 검색·페이지네이션은
- * `toolbar`로 주입하고 필터링된 `rows`를 넘긴다. 서버 렌더링 환경에서도 그대로 쓸 수 있다.
+ * `toolbar`로 주입하고 필터링된 `rows`를 넘긴다.
+ *
+ * 기본 빈 문구는 i18n(`board.empty`)을 따른다 — 전에는 한국어가 박혀 영어 화면에서도 한국어였다. 그래서 i18n 훅을 쓰는
+ * 클라이언트 컴포넌트('use client')다(서버 렌더링(SSR)은 그대로 된다).
  * @public
  */
 export default function Board<T>({ columns, rows, rowKey, title, toolbar, empty, loading, caption, className, }: BoardProps<T>): import("react").JSX.Element;

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

@@ -1,12 +1,18 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cx } from '../utils/cx';
+import { useTranslation } from 'react-i18next';
 import './Board.css';
 /**
  * 게시판형 목록 표. 상태를 갖지 않는 표현 컴포넌트이므로 검색·페이지네이션은
- * `toolbar`로 주입하고 필터링된 `rows`를 넘긴다. 서버 렌더링 환경에서도 그대로 쓸 수 있다.
+ * `toolbar`로 주입하고 필터링된 `rows`를 넘긴다.
+ *
+ * 기본 빈 문구는 i18n(`board.empty`)을 따른다 — 전에는 한국어가 박혀 영어 화면에서도 한국어였다. 그래서 i18n 훅을 쓰는
+ * 클라이언트 컴포넌트('use client')다(서버 렌더링(SSR)은 그대로 된다).
  * @public
  */
-export default function Board({ columns, rows, rowKey, title, toolbar, empty = '등록된 항목이 없습니다.', loading, caption, className = '', }) {
+export default function Board({ columns, rows, rowKey, title, toolbar, empty, loading, caption, className = '', }) {
+    const { t } = useTranslation();
     const showEmpty = !loading && rows.length === 0;
-    return (_jsxs("div", { className: cx('board', className), children: [title || toolbar ? (_jsxs("div", { className: "board__head", children: [title ? _jsx("h2", { className: "board__title", children: title }) : _jsx("span", {}), toolbar ? _jsx("div", { className: "board__toolbar", children: toolbar }) : null] })) : null, _jsxs("table", { className: "board__table", children: [caption ? _jsx("caption", { className: "board__caption", children: caption }) : null, _jsx("thead", { children: _jsx("tr", { children: columns.map((col) => (_jsx("th", { scope: "col", className: cx('board__th', `board__cell--${col.headerAlign ?? col.align ?? 'left'}`), style: col.width ? { width: col.width } : undefined, children: col.header }, col.key))) }) }), _jsx("tbody", { children: loading ? (_jsx("tr", { children: _jsx("td", { className: "board__state", colSpan: columns.length, children: loading }) })) : showEmpty ? (_jsx("tr", { children: _jsx("td", { className: "board__state", colSpan: columns.length, children: empty }) })) : (rows.map((row, i) => (_jsx("tr", { className: "board__row", children: columns.map((col) => (_jsx("td", { className: cx('board__td', `board__cell--${col.align ?? 'left'}`), children: col.render(row, i) }, col.key))) }, rowKey(row, i))))) })] })] }));
+    return (_jsxs("div", { className: cx('board', className), children: [title || toolbar ? (_jsxs("div", { className: "board__head", children: [title ? _jsx("h2", { className: "board__title", children: title }) : _jsx("span", {}), toolbar ? _jsx("div", { className: "board__toolbar", children: toolbar }) : null] })) : null, _jsxs("table", { className: "board__table", children: [caption ? _jsx("caption", { className: "board__caption", children: caption }) : null, _jsx("thead", { children: _jsx("tr", { children: columns.map((col) => (_jsx("th", { scope: "col", className: cx('board__th', `board__cell--${col.headerAlign ?? col.align ?? 'left'}`), style: col.width ? { width: col.width } : undefined, children: col.header }, col.key))) }) }), _jsx("tbody", { children: loading ? (_jsx("tr", { children: _jsx("td", { className: "board__state", colSpan: columns.length, children: loading }) })) : showEmpty ? (_jsx("tr", { children: _jsx("td", { className: "board__state", colSpan: columns.length, children: empty ?? t('board.empty', '등록된 항목이 없습니다.') }) })) : (rows.map((row, i) => (_jsx("tr", { className: "board__row", children: columns.map((col) => (_jsx("td", { className: cx('board__td', `board__cell--${col.align ?? 'left'}`), children: col.render(row, i) }, col.key))) }, rowKey(row, i))))) })] })] }));
 }

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

@@ -10,7 +10,7 @@ import MenuTooltip from './Tooltip/MenuTooltip';
 // Tooltip.tsx만 이 CSS를 import하는데 BottomNav는 그 컴포넌트를 거치지 않아,
 // 프로덕션에서 청크가 갈리면 스타일 없이 렌더될 수 있다.
 import './Tooltip/Tooltip.css';
-import { useAnchoredMenu } from '../hooks/useAnchoredMenu';
+import { useAnchoredMenu, anchoredMenuZIndex } from '../hooks/useAnchoredMenu';
 import { useTranslation } from 'react-i18next';
 const BTN_SIZE = 52;
 const BTN_GAP = 10;
@@ -59,17 +59,18 @@ export default function BottomNav({ items = [], activeKey, onChange, appMode, on
     // 넘친 nav 항목이 있거나 유틸(moreItems)이 있으면 더보기(…) 버튼을 노출
     const showMore = overflow || moreItems.length > 0;
     useEffect(() => { 더보기섰음Ref.current = showMore; });
-    const computeMenuStyle = useCallback((rect) => ({
+    const computeMenuStyle = useCallback((rect, trigger) => ({
         position: 'fixed',
         bottom: window.innerHeight - rect.top + 8,
         right: window.innerWidth - rect.right,
-        zIndex: 10000,
+        zIndex: anchoredMenuZIndex(trigger),
     }), []);
     const moreMenuId = useId();
     const { open: moreOpen, toggle: handleToggleMore, close: handleCloseMore, style: menuStyle, triggerRef: moreRef, menuRef } = useAnchoredMenu({
         computeStyle: computeMenuStyle,
         onScroll: 'ignore',
-        onResize: 'ignore',
+        /* 기기를 돌리면(가로↔세로) 옛 좌표에 남아 메뉴가 엉뚱한 곳·화면 밖에 떴다 — 다시 잰다 */
+        onResize: 'reposition',
     });
     /* 단추 이름에 개수를 붙인다 — 배지는 aria-hidden 이라 개수는 이름으로만 전해진다. */
     const nameWithCount = useCallback((label, count) => count > 0 ? t('nav.badgeLabel', { label, count, defaultValue: '{{label}}, {{count}}개' }) : label, [t]);

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

@@ -54,6 +54,15 @@
   color: var(--color-darkGray);
 }
 
+/* 갈 곳이 없는 중간 항목 — 링크·단추와 같은 색이되 누를 수 있어 보이지 않게(밑줄·손 모양 없음) */
+.breadcrumb__text {
+  color: var(--color-gray);
+}
+
+a.breadcrumb__link {
+  text-decoration: none;
+}
+
 .breadcrumb__separator {
   display: inline-flex;
   align-items: center;

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

@@ -2,12 +2,23 @@ import './Breadcrumb.css';
 /** @public */
 export interface BreadcrumbItem {
     label: string;
+    /** 누르면 부른다 — 주면 단추(`href` 도 주면 링크에 건다). 마지막 항목(지금 쪽)에서는 무시한다. */
     onClick?: () => void;
+    /** 주면 링크(`<a>`)로 그린다. 마지막 항목(지금 쪽)에서는 무시한다. `onClick`·`href` 가 둘 다 없는 중간 항목은 누를 수 없는 글자다. */
+    href?: string;
+    /** 선택. 링크의 target(`href` 와 함께). */
+    target?: string;
+    /** 선택. 링크의 rel. `target="_blank"` 이고 안 주면 `noopener noreferrer`. */
+    rel?: string;
 }
 /** @public */
 export interface BreadcrumbProps {
     items: BreadcrumbItem[];
     className?: string;
 }
-/** @public */
+/**
+ * 이동 경로. 마지막 항목은 지금 쪽(`aria-current="page"`, 누를 수 없는 글자 — onClick·href 무시).
+ * 앞 항목은 `href` 가 있으면 링크, `onClick` 만 있으면 단추, 둘 다 없으면 글자다.
+ * @public
+ */
 export default function Breadcrumb({ items, className }: BreadcrumbProps): import("react").JSX.Element;

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

@@ -3,13 +3,19 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useTranslation } from 'react-i18next';
 import './Breadcrumb.css';
 import Icon from './Icon';
-/** @public */
+/**
+ * 이동 경로. 마지막 항목은 지금 쪽(`aria-current="page"`, 누를 수 없는 글자 — onClick·href 무시).
+ * 앞 항목은 `href` 가 있으면 링크, `onClick` 만 있으면 단추, 둘 다 없으면 글자다.
+ * @public
+ */
 export default function Breadcrumb({ items, className = '' }) {
     const { t } = useTranslation();
     return (
     /* 영어로 박혀 있어 한국어 화면에서도 낭독기가 "breadcrumb" 이라고 읽었다 — 사전을 탄다 */
     _jsx("nav", { className: `breadcrumb ${className}`.trim(), "aria-label": t('breadcrumb.ariaLabel', '이동 경로'), children: _jsx("ol", { className: "breadcrumb__list", children: items.map((item, index) => {
                 const isLast = index === items.length - 1;
-                return (_jsxs("li", { className: "breadcrumb__item", children: [isLast ? (_jsx("span", { className: "breadcrumb__current body-3", "aria-current": "page", children: item.label })) : (_jsx("button", { type: "button", className: "breadcrumb__link body-3", onClick: item.onClick, children: item.label })), !isLast && (_jsx(Icon, { icon: "chevron-right", size: 14, className: "breadcrumb__separator" }))] }, index));
+                return (_jsxs("li", { className: "breadcrumb__item", children: [isLast ? (_jsx("span", { className: "breadcrumb__current body-3", "aria-current": "page", children: item.label })) : item.href ? (_jsx("a", { className: "breadcrumb__link body-3", href: item.href, target: item.target, rel: item.rel ?? (item.target === '_blank' ? 'noopener noreferrer' : undefined), onClick: item.onClick, children: item.label })) : item.onClick ? (_jsx("button", { type: "button", className: "breadcrumb__link body-3", onClick: item.onClick, children: item.label })) : (
+                        /* 갈 곳이 없는 중간 항목은 글자 — 전에는 늘 단추라 눌러도 아무 일 없는 단추가 Tab 자리를 차지했다 */
+                        _jsx("span", { className: "breadcrumb__text body-3", children: item.label })), !isLast && (_jsx(Icon, { icon: "chevron-right", size: 14, className: "breadcrumb__separator" }))] }, index));
             }) }) }));
 }

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

@@ -1,6 +1,8 @@
 .bulk-bar {
   position: sticky;
   bottom: 24px;
+  /* 층을 준다 — 없으면(auto) 뒤에 오는 position 있는 내용(표 머리·칩)이 막대 위로 그려졌다. 메뉴·창 아래(tokens.css 서열) */
+  z-index: var(--z-bulk-bar, 600);
   display: flex;
   align-items: center;
   justify-content: space-between;

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

@@ -1,6 +1,7 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useRef, useState } from 'react';
+import { useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { moveFocusOutside } from '../hooks/focusReturn';
 import { useTranslation } from 'react-i18next';
 import './BulkBar.css';
 import Button from './Button';
@@ -14,6 +15,24 @@ export default function BulkBar({ count, actions, onClear, clearLabel: clearLabe
        줄바꿈 여부를 높이 문턱값으로 재면 칩 크기나 글꼴이 바뀔 때마다 틀리므로,
        자식들이 실제로 같은 줄에 있는지(offsetTop)를 본다. */
     const contentRef = useRef(null);
+    /* 개수가 0 이 되어 inert 가 될 때 포커스가 안(선택 해제·삭제 단추)에 있으면 body 로 떨어졌다 — 바를 연 요소(바가 나타날 때
+       포커스였던 곳, 대개 방금 누른 체크박스)로, 없으면 바 바로 앞의 포커스 받을 수 있는 요소로 옮긴다.
+       inert 가 걸린 뒤 브라우저가 포커스를 치우기 전(레이아웃 효과)에 옮긴다. */
+    const barRef = useRef(null);
+    const openerRef = useRef(null);
+    const prevShowRef = useRef(show);
+    useLayoutEffect(() => {
+        const bar = barRef.current;
+        const 전 = prevShowRef.current;
+        prevShowRef.current = show;
+        if (show && !전) {
+            const a = typeof document !== 'undefined' ? document.activeElement : null;
+            openerRef.current = a && a !== document.body && !bar?.contains(a) ? a : null;
+        }
+        else if (!show && 전 && bar && bar.contains(document.activeElement)) {
+            moveFocusOutside(bar, openerRef.current);
+        }
+    }, [show]);
     const [stacked, setStacked] = useState(false);
     /* 세로로 쌓으면 단추 칸이 좁아져 내용 칸이 넓어지고, 넓어진 칸에서 한 줄에 들어가 다시 가로로 돌리면 칸이 좁아져 또 넘친다 —
        문턱이 하나라 **매 프레임 오갔다**(말귀 단어 고름 막대, 칩 7~12개). 되돌릴 때는 "가로일 때의 칸 폭" 에 한 줄로 들어가는지로
@@ -72,7 +91,7 @@ export default function BulkBar({ count, actions, onClear, clearLabel: clearLabe
             막대obs.observe(막대);
         return () => { obs.disconnect(); 막대obs.disconnect(); };
     }, [content, count]);
-    return (_jsxs("div", { className: `bulk-bar ${show ? 'bulk-bar--visible' : ''}`, 
+    return (_jsxs("div", { ref: barRef, className: `bulk-bar ${show ? 'bulk-bar--visible' : ''}`, 
         /* 숨은 막대는 CSS 로 투명(opacity 0)할 뿐 DOM 에 그대로 있다 — 예전에는 그 안의
            단추가 Tab 순서와 낭독기에 남아, 보이지 않는 '선택 해제'·'삭제' 에 포커스가 갔다.
            inert 로 포커스·낭독기에서 함께 뺀다(보이는 모양은 CSS 그대로). aria-hidden 은

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

@@ -1,5 +1,15 @@
+import { type ReactElement, type RefAttributes } from 'react';
 import './Button.css';
 export type { ButtonVariant, ButtonLayoutType, ButtonShape, ButtonProps } from './buttonTypes';
 import type { ButtonProps } from './buttonTypes';
-/** @public */
-export default function Button(props: ButtonProps): import("react").JSX.Element;
+/**
+ * 단추(또는 `href` 가 있으면 링크). `ref` 를 주면 그 요소(`HTMLButtonElement`, 링크면 `HTMLAnchorElement`)에 닿는다 —
+ * forwardRef 라 React 16.8~18 에서도 된다.
+ * @public
+ */
+type ButtonComponent = {
+    (props: ButtonProps & RefAttributes<HTMLButtonElement | HTMLAnchorElement>): ReactElement | null;
+    displayName?: string;
+};
+declare const Button: ButtonComponent;
+export default Button;

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

@@ -1,14 +1,16 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { cx } from '../utils/cx';
-import { useCallback, useEffect, useRef, useState } from 'react';
+import { forwardRef, useCallback, useEffect, useId, useRef, useState } from 'react';
 import './Button.css';
 import Icon from './Icon';
 import InfoTooltip from "./Tooltip/InfoTooltip";
 import DescriptionTooltip from "./Tooltip/DescriptionTooltip";
-/** @public */
-export default function Button(props) {
-    const { size = 48, type: explicitType, htmlType, href, target, rel, icon, rightIcon, label: labelProp, count, subLabel, children, ariaLabel, variant = 'default', align = 'center', selected, toggleable = false, disabled = false, useLabel = true, useBorder = true, useBG = true, useDisabledCovered = false, useDisabledInvisible = false, width, minWidth, onClick, onDisabledClick, showTooltipInfo = false, tooltipInfoText = null, tooltipDescription = null, tooltipOnly = false, iconSize = 'medium', iconColor, shape = 'rounded', color, className, ...rest } = props;
+import { isTouchPointer, recentlyTouched, useTouchToggle } from '../hooks/touchToggle';
+/* **ref 는 forwardRef 로 받는다** — React 19 는 ref 를 props 로 넘기지만 peer 는 16.8~ 라, React 18(kscan) 에서는 함수 컴포넌트에 준
+   ref 가 버려진다. 게다가 전에는 안쪽 ref(`btnRef`)가 props 에서 온 ref 를 덮어써 19 에서도 부르는 쪽 ref 가 비었다. 두 ref 를 잇는다. */
+function ButtonInner(props, forwardedRef) {
+    const { size = 48, type: explicitType, htmlType, href, target, rel, icon, rightIcon, label: labelProp, count, subLabel, children, ariaLabel, variant = 'default', align = 'center', selected, toggleable = false, ariaExpanded, ariaControls, disabled = false, useLabel = true, useBorder = true, useBG = true, useDisabledCovered = false, useDisabledInvisible = false, width, minWidth, onClick, onDisabledClick, showTooltipInfo = false, tooltipInfoText = null, tooltipDescription = null, tooltipOnly = false, iconSize = 'medium', iconColor, shape = 'rounded', color, className, ...rest } = props;
     const sizeKey = typeof size === 'string' && isNaN(Number(size))
         ? size.toLowerCase()
         : String(Number(size) || 48);
@@ -44,11 +46,27 @@ export default function Button(props) {
     const type = explicitType ?? defaultType;
     const sizeTypeClass = `${sizeBase}--${type}`;
     const btnRef = useRef(null);
+    /* 안쪽 ref 와 부르는 쪽 ref(객체·함수)를 한 요소에 함께 건다 */
+    const 바깥ref = useRef(forwardedRef);
+    바깥ref.current = forwardedRef;
+    const 요소잇기 = useCallback((el) => {
+        btnRef.current = el;
+        const r = 바깥ref.current;
+        if (typeof r === 'function')
+            r(el);
+        else if (r)
+            r.current = el;
+    }, []);
     const prevDisabledRef = useRef(disabledProp);
     const [internalSelected, setInternalSelected] = useState(Boolean(selected));
     const [tooltipVisible, setTooltipVisible] = useState(false);
     const [anchorRect, setAnchorRect] = useState(null);
     const handleTooltipClose = useCallback(() => setTooltipVisible(false), []);
+    /* 초점을 가진 채 막히는 단추 — native `disabled` 를 걸면 브라우저가 초점을 body 로 뺀다(쪽 넘김 끝 쪽·순서 목록 위로·
+       글자 크기 끝값처럼 **누른 결과로 그 단추가 막히는** 자리). 초점이 있는 동안에는 `aria-disabled` 로만 막고,
+       초점을 잃으면(blur) native 로 돌아간다. */
+    const [hasFocus, setHasFocus] = useState(false);
+    const describeId = useId();
     /* 예전에는 "열린 채로 disabled 가 되면 즉시 닫기" 가 여기 있었다. 그때는
        막히는 순간 `pointer-events: none` 이 걸려 **pointerleave 가 안 와** 툴팁이
        영영 붙어 있었기 때문이다. 이제 포인터를 안 끄므로 leave 가 제대로 오고,
@@ -92,9 +110,11 @@ export default function Button(props) {
     const isSelected = typeof selected === 'boolean' ? Boolean(selected) : internalSelected;
     // toggleable 또는 controlled selected가 있을 때만 aria-pressed 설정
     // 그 밖에는 소비자가 넘긴 aria-pressed 를 그대로 둔다(아이콘이 바뀌는 재생/멈춤 단추 등) — 전에는 undefined 로 덮었다
-    const ariaPressed = (toggleable || typeof selected === 'boolean')
-        ? (isSelected ? 'true' : 'false')
-        : rest['aria-pressed'];
+    /* 여닫이(ariaExpanded)는 눌림이 아니라 펼침으로 알린다 — 둘을 함께 달면 "눌림, 펼쳐짐" 으로 겹쳐 읽힌다 */
+    const ariaPressed = typeof ariaExpanded === 'boolean' ? undefined
+        : (toggleable || typeof selected === 'boolean')
+            ? (isSelected ? 'true' : 'false')
+            : rest['aria-pressed'];
     const classes = cx('button', sizeBase, sizeTypeClass, variantClass, alignClass, shapeClass, isSelected ? 'is-selected' : null, !useBG ? 'button--no-bg' : null, tooltipOnly ? 'button--tooltip-only' : null, className);
     const iconClassName = `button__icon button__icon--${iconSize}`;
     const subLabels = Array.isArray(subLabel) ? subLabel : (subLabel !== undefined ? [subLabel] : []);
@@ -123,7 +143,13 @@ export default function Button(props) {
         떠남정리(e);
     };
     const handleClickInternal = (e) => {
+        if (tooltipOnly && hasTooltip)
+            톡토글.touchPress(e.currentTarget);
         if (disabledProp) {
+            if (hasTooltip)
+                톡토글.touchPress(e.currentTarget);
+            /* native disabled 가 아닌 막힌 단추(초점 유지·onDisabledClick)는 click 이 온다 — 폼 안이면 제출되지 않게 기본 동작을 막는다 */
+            e.preventDefault();
             onDisabledClick?.(e);
             return;
         }
@@ -148,6 +174,14 @@ export default function Button(props) {
             setAnchorRect(null);
         }
     }, [showTooltipInfo, tooltipDescription]);
+    /* 터치 — 호버 툴팁이 톡하면 열렸다 떼자마자 닫혀(Android 는 초점으로 다시 열림) 막힌 단추의 사유·칩 설명을 읽을 수 없었다.
+       **막힌 단추·tooltipOnly 칩**은 톡으로 열고 닫는다(막힌 단추는 click 이 안 와 pointerup, 포인터조차 안 오면 감싼 요소의 touchend).
+       누르는 단추(삭제·재생 등)는 터치에서 툴팁을 띄우지 않는다 — 누르면 할 일을 하고 끝난다. 마우스 동작은 그대로. */
+    const hasTooltip = Boolean(showTooltipInfo || tooltipDescription);
+    const 톡토글 = useTouchToggle(tooltipVisible, (next) => { if (next)
+        showTooltipFn();
+    else
+        hideTooltipFn(); }, btnRef, { enabled: hasTooltip && (disabledProp || tooltipOnly), fallbackOnParent: hasTooltip && disabledProp });
     // restProps에서 Button이 직접 처리하는 props 제거
     const restProps = { ...rest };
     delete restProps.disabled;
@@ -159,6 +193,7 @@ export default function Button(props) {
     delete restProps.onMouseLeave;
     delete restProps.onPointerEnter;
     delete restProps.onPointerLeave;
+    delete restProps.onPointerUp;
     delete restProps.onFocus;
     delete restProps.onBlur;
     if (disabledProp) {
@@ -180,6 +215,13 @@ export default function Button(props) {
     const ariaLabelString = typeof ariaLabel === 'string' ? ariaLabel
         : typeof label === 'string' ? label
             : tooltipText;
+    /* 툴팁 문구를 설명(aria-describedby)으로 잇는다 — 막힌 단추의 사유·칩의 설명이 마우스로만 보이고 낭독되지 않았다.
+       이름과 같은 문구(아이콘 단추의 이름 겸 툴팁)는 두 번 읽히므로 잇지 않는다. */
+    const describeText = tooltipDescription
+        ? [tooltipDescription.title, ...(tooltipDescription.items ?? [])].filter(Boolean).join('. ')
+        : showTooltipInfo && tooltipText && tooltipText !== ariaLabelString ? tooltipText : '';
+    const consumerDescribedBy = typeof rest['aria-describedby'] === 'string' ? rest['aria-describedby'] : undefined;
+    const ariaDescribedBy = [consumerDescribedBy, describeText ? describeId : null].filter(Boolean).join(' ') || undefined;
     const renderIcon = (iconVal, label) => (_jsx(Icon, { icon: iconVal, label: label ?? ariaLabelString, className: iconClassName, imgClassName: "button__icon-img", maskClassName: "button__icon-mask", svgClassName: "button__icon-svg" }));
     const renderContent = () => {
         if (type === 'dot') {
@@ -193,29 +235,44 @@ export default function Button(props) {
     /* href 가 있고 비활성이 아니면 링크로 렌더한다. */
     const isLink = !!href && !disabledProp;
     const Root = (isLink ? 'a' : 'button');
-    return (_jsxs(_Fragment, { children: [_jsx(Root, { ...restProps, ref: btnRef, ...(isLink
+    return (_jsxs(_Fragment, { children: [_jsxs(Root, { ...restProps, ref: 요소잇기, ...(isLink
                     ? { href, target, rel: rel ?? (target === '_blank' ? 'noreferrer' : undefined) }
-                    : { type: htmlType, disabled: disabledProp && !onDisabledClick }), className: classes, "aria-pressed": ariaPressed, "aria-label": ariaLabelString, "aria-disabled": disabledProp && (isLink || !!onDisabledClick) ? true : undefined, style: style, onClick: handleClickInternal, onMouseLeave: handleMouseLeave, onPointerEnter: (e) => {
-                    showTooltipFn();
+                    : { type: htmlType, disabled: disabledProp && !onDisabledClick && !hasFocus }), className: classes, "aria-pressed": ariaPressed, "aria-expanded": typeof ariaExpanded === 'boolean' ? ariaExpanded : rest['aria-expanded'], "aria-controls": ariaControls ?? rest['aria-controls'], "aria-label": ariaLabelString, "aria-disabled": disabledProp && (isLink || !!onDisabledClick || hasFocus) ? true : undefined, "aria-describedby": ariaDescribedBy, style: style, onClick: handleClickInternal, onMouseLeave: handleMouseLeave, onPointerEnter: (e) => {
+                    if (!isTouchPointer(e))
+                        showTooltipFn();
                     if (!disabledProp && typeof rest.onPointerEnter === 'function')
                         rest.onPointerEnter(e);
                 }, onPointerLeave: (e) => {
-                    hideTooltipFn();
+                    if (!isTouchPointer(e))
+                        hideTooltipFn();
                     if (!disabledProp && typeof rest.onPointerLeave === 'function')
                         rest.onPointerLeave(e);
+                }, onPointerUp: (e) => {
+                    // 막힌 단추는 click 이 오지 않는다 — 톡을 뗄 때 뒤집는다
+                    if (disabledProp && hasTooltip)
+                        톡토글.touchPress(e.currentTarget);
+                    if (!disabledProp && typeof rest.onPointerUp === 'function')
+                        rest.onPointerUp(e);
                 }, onFocus: (e) => {
-                    showTooltipFn();
+                    setHasFocus(true);
+                    // 톡으로 온 초점(Android)은 툴팁을 열지 않는다 — 톡 토글이 정한다
+                    if (!recentlyTouched())
+                        showTooltipFn();
                     if (!disabledProp && typeof rest.onFocus === 'function')
                         rest.onFocus(e);
                 }, onBlur: (e) => {
+                    setHasFocus(false);
                     if (!disabledProp)
                         떠남정리(e);
                     hideTooltipFn();
                     if (!disabledProp && typeof rest.onBlur === 'function')
                         rest.onBlur(e);
-                }, children: renderContent() }), tooltipVisible && tooltipDescription
+                }, children: [renderContent(), describeText ? _jsx("span", { id: describeId, hidden: true, "aria-label": describeText }) : null] }), tooltipVisible && tooltipDescription
                 ? _jsx(DescriptionTooltip, { anchorRect: anchorRect, title: tooltipDescription.title, items: tooltipDescription.items, onClose: handleTooltipClose })
                 : tooltipVisible && tooltipText
                     ? _jsx(InfoTooltip, { anchorRect: anchorRect, text: tooltipText, onClose: handleTooltipClose })
                     : null] }));
 }
+const Button = forwardRef(ButtonInner);
+Button.displayName = 'Button';
+export default Button;

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

@@ -11,7 +11,7 @@ export type Visit = {
     status?: VisitStatus;
 };
 /** @public */
-export default function Calendar({ visits, onVisitClick, onVisitMove, onDayClick, }: {
+export default function Calendar({ visits, onVisitClick, onVisitMove, onDayClick, today, }: {
     visits?: Visit[];
     onVisitClick?: (visit: Visit) => void;
     onVisitMove?: (visitId: string | number, newDate: string) => void;
@@ -20,4 +20,9 @@ export default function Calendar({ visits, onVisitClick, onVisitMove, onDayClick
      * 주지 않으면 칸은 눌리지 않고 손 모양도 뜨지 않는다(못 하는 일을 내밀지 않는다).
      */
     onDayClick?: (date: string) => void;
+    /**
+     * 선택. '오늘' 로 쓸 날 'YYYY-MM-DD' — 처음 여는 달과 오늘 표시가 이 날을 따른다.
+     * 로컬 앱·SSR 처럼 부르는 쪽이 오늘을 정하는 자리에서 넘긴다. 없거나 꼴이 틀리면 KST 오늘(기본).
+     */
+    today?: string;
 }): import("react").JSX.Element;

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

@@ -4,18 +4,18 @@ import { useCallback, useMemo, useState, useRef } from 'react';
 import { useTranslation } from 'react-i18next';
 import Icon from './Icon';
 import { formatTimeHM } from '../utils/format';
-import { getTodayKst } from '../utils/date';
+import { todayYmdOr } 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, }) {
+export default function Calendar({ visits = [], onVisitClick, onVisitMove, onDayClick, today, }) {
     const { t } = useTranslation();
     const DOW = useMemo(() => t('calendar.dow', { returnObjects: true }), [t]);
     /* '오늘' 은 KST 의 날 — 방문 날짜가 KST 달력(toKstYmd)이라, 기기 달력으로 열면 해외 기기에서 오늘 방문이 안 보이는 달에 있고
        오늘 표시가 다른 날에 붙었다(해외 기기 공식 지원) */
-    const 오늘Ymd = getTodayKst();
+    const 오늘Ymd = todayYmdOr(today);
     const [year, setYear] = useState(() => Number(오늘Ymd.slice(0, 4)));
     const [month, setMonth] = useState(() => Number(오늘Ymd.slice(5, 7)) - 1);
     const [dragOverDate, setDragOverDate] = useState(null);

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

@@ -10,5 +10,11 @@ export interface DatePickerProps {
     /** 값이 없을 때 보이는 문구. 기본은 사전의 `datePicker.chooseDate`('날짜 선택') */
     placeholder?: string;
     className?: string;
+    /**
+     * 선택. '오늘' 로 쓸 날 'YYYY-MM-DD' — 오늘 표시, 값 없이 열 때의 달·포커스가 이 날을 따른다.
+     * 로컬 앱·SSR 처럼 부르는 쪽이 오늘을 정하는 자리에서 넘긴다. 없거나 꼴이 틀리면 KST 오늘(기본).
+     * (min·max 는 이 값과 따로다 — '오늘부터' 를 막으려면 min 에도 같은 날을 넘긴다.)
+     */
+    today?: string;
 }
-export default function DatePicker({ value, onChange, size, min, max, disabled, placeholder: placeholderProp, className, }: DatePickerProps): import("react").JSX.Element;
+export default function DatePicker({ value, onChange, size, min, max, disabled, placeholder: placeholderProp, className, today, }: DatePickerProps): import("react").JSX.Element;