@ncds/ui-admin 1.8.13 → 1.8.15

package/dist/cjs/src/components/navigation/pagination/Pagination.js

@@ -33,6 +33,13 @@ const Pagination = _ref => {
     }
   };
   (0, _react.useEffect)(() => {
+    const lastGroupStart = Math.max(1, Math.floor((totalPage - 1) / pageCount) * pageCount + 1);
+    // totalPage/pageCount 가 줄어 start 가 마지막 그룹을 넘으면 마지막 그룹으로 보정한다.
+    // (예: 100→50 페이지로 축소 시 start 가 91 에 머물러 범위 밖 버튼을 표시하던 문제)
+    if (start > lastGroupStart) {
+      setStart(lastGroupStart);
+      return;
+    }
     if (currentPage === start + pageCount) {
       setStart(start + pageCount);
     }
@@ -47,10 +54,13 @@ const Pagination = _ref => {
       setStart(1);
     }
     if (currentPage === totalPage) {
-      const lastGroupStart = Math.floor((totalPage - 1) / pageCount) * pageCount + 1;
       setStart(lastGroupStart);
     }
-  }, [currentPage]);
+    // start 는 이 effect 가 setStart 로 갱신하는 대상이라 deps 에서 제외한다(넣으면 자기 갱신으로
+    // 재실행). currentPage 외에 totalPage/pageCount 도 추적해, 이들이 줄어 start 가 범위를 벗어나면
+    // 위에서 보정한다.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [currentPage, totalPage, pageCount]);
   return (0, _jsxRuntime.jsxs)("div", {
     className: (0, _classnames.default)('ncua-pagination', `ncua-pagination--${breakPoint}`, className),
     children: [showJumpPageButton && (0, _jsxRuntime.jsxs)(_jsxRuntime.Fragment, {

package/dist/cjs/src/components/navigation/pagination/__tests__/Pagination.test.js

@@ -0,0 +1,62 @@
+"use strict";
+
+var _react = require("react");
+var _client = require("react-dom/client");
+var _testUtils = require("react-dom/test-utils");
+var _vitest = require("vitest");
+var _Pagination = require("../Pagination");
+// @vitest-environment jsdom
+
+const ITEM_COUNT_PER_PAGE = 10;
+const PAGE_GROUP_SIZE = 10;
+const TOTAL_COUNT_100_PAGES = 1000;
+const TOTAL_COUNT_50_PAGES = 500;
+const CURRENT_PAGE = 91; // 100페이지 기준 마지막 그룹(91~100)을 보던 페이지
+const GROUP_START_100_PAGES = 91; // currentPage=91 일 때의 그룹 시작
+const GROUP_START_50_PAGES = 41; // totalPage=50 으로 줄었을 때의 마지막 그룹 시작
+const LAST_PAGE_50 = 50;
+let root = null;
+let container = null;
+function render(props) {
+  if (!container) {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = (0, _client.createRoot)(container);
+  }
+  (0, _testUtils.act)(() => {
+    root?.render(/*#__PURE__*/(0, _react.createElement)(_Pagination.Pagination, props));
+  });
+  return container;
+}
+(0, _vitest.afterEach)(() => {
+  if (root && container) {
+    (0, _testUtils.act)(() => root?.unmount());
+    container.remove();
+  }
+  root = null;
+  container = null;
+});
+const pageNums = el => Array.from(el.querySelectorAll('.ncua-pagination__page-num')).map(b => Number(b.textContent));
+(0, _vitest.describe)('#332 Pagination — totalPage 축소 시 start 보정', () => {
+  (0, _vitest.it)('totalPage 가 줄면 start 를 마지막 그룹으로 보정하고 범위 밖 페이지 버튼을 표시하지 않는다', () => {
+    // 1) 100 페이지에서 91 페이지 보는 중 → 91~100 그룹 표시
+    const el = render({
+      totalCount: TOTAL_COUNT_100_PAGES,
+      itemCountPerPage: ITEM_COUNT_PER_PAGE,
+      pageCount: PAGE_GROUP_SIZE,
+      currentPage: CURRENT_PAGE
+    });
+    (0, _vitest.expect)(pageNums(el)[0]).toBe(GROUP_START_100_PAGES);
+    // 2) 데이터가 50 페이지로 줄어듦 (currentPage 는 그대로 — 부모가 clamp 안 한 상황)
+    render({
+      totalCount: TOTAL_COUNT_50_PAGES,
+      itemCountPerPage: ITEM_COUNT_PER_PAGE,
+      pageCount: PAGE_GROUP_SIZE,
+      currentPage: CURRENT_PAGE
+    });
+    const nums = pageNums(el);
+    // 마지막 그룹(41~50)으로 보정되고, totalPage(50)를 넘는 버튼은 없어야 한다
+    (0, _vitest.expect)(nums[0]).toBe(GROUP_START_50_PAGES);
+    (0, _vitest.expect)(Math.max(...nums)).toBeLessThanOrEqual(LAST_PAGE_50);
+  });
+});

package/dist/cjs/src/components/overlays/tooltip/Tooltip.js

@@ -10,6 +10,7 @@ var _classnames = _interopRequireDefault(require("classnames"));
 var _react = require("react");
 var _reactDom = require("react-dom");
 var _ButtonCloseX = require("../../action/button/ButtonCloseX");
+var _utils = require("./utils");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 const ICON_SIZE_SM = 14;
 const ICON_SIZE_DEFAULT = 16;
@@ -71,9 +72,16 @@ const computePanelCoords = (prefer, anchor, panel) => {
   }
   left = Math.max(VIEWPORT_MARGIN, Math.min(left, window.innerWidth - panel.width - VIEWPORT_MARGIN));
   top = Math.max(VIEWPORT_MARGIN, Math.min(top, window.innerHeight - panel.height - VIEWPORT_MARGIN));
+  // 경계 보정으로 패널이 앵커 중심에서 밀렸을 때도 화살표(::after)가 앵커를 가리키도록
+  // 패널 내 X 오프셋 계산 (top/bottom 계열만 — SCSS의 --top/--bottom 규칙이 소비)
+  let arrowX = null;
+  if (calculatedPosition === 'top' || calculatedPosition === 'bottom') {
+    arrowX = (0, _utils.calculateArrowOffsetX)(anchor.left + anchor.width / 2, left, panel.width);
+  }
   return {
     top: Math.round(top),
     left: Math.round(left),
+    arrowX,
     calculatedPosition
   };
 };
@@ -86,6 +94,9 @@ const buildPanelStyle = (disablePortal, coords, visible, zIndex) => {
     top: `${coords.top}px`,
     left: `${coords.left}px`,
     opacity,
+    ...(coords.arrowX !== null && {
+      '--ncua-tooltip-arrow-x': `${coords.arrowX}px`
+    }),
     ...(zIndex && {
       zIndex
     })
@@ -138,7 +149,8 @@ const Tooltip = _ref => {
   const [mounted, setMounted] = (0, _react.useState)(false);
   const [coords, setCoords] = (0, _react.useState)({
     top: OFFSCREEN,
-    left: OFFSCREEN
+    left: OFFSCREEN,
+    arrowX: null
   });
   const [calculatedPosition, setCalculatedPosition] = (0, _react.useState)(position === 'auto' ? 'bottom' : position);
   const [isVisible, setIsVisible] = (0, _react.useState)(false);
@@ -160,7 +172,8 @@ const Tooltip = _ref => {
     const next = computePanelCoords(position, anchor, panel);
     setCoords({
       top: next.top,
-      left: next.left
+      left: next.left,
+      arrowX: next.arrowX
     });
     setCalculatedPosition(next.calculatedPosition);
   }, [position, disablePortal]);

package/dist/cjs/src/components/overlays/tooltip/__tests__/utils.test.js

@@ -0,0 +1,40 @@
+"use strict";
+
+var _vitest = require("vitest");
+var _utils = require("../utils");
+// 공통 픽스처 — 너비 300px 패널이 viewport 왼쪽 여백(8px)에 클램핑된 상태를 가정
+const PANEL_WIDTH = 300;
+const CLAMPED_LEFT = 8;
+(0, _vitest.describe)('calculateArrowOffsetX — 화살표가 앵커 중심을 가리키도록 패널 내 X 오프셋 계산', () => {
+  (0, _vitest.it)('패널이 클램핑되지 않으면(앵커 중심 = 패널 중심) 패널 너비의 절반을 반환한다', () => {
+    const anchorCenterX = 200;
+    const centeredPanelLeft = 50;
+    const panelHalfWidth = 150;
+    (0, _vitest.expect)((0, _utils.calculateArrowOffsetX)(anchorCenterX, centeredPanelLeft, PANEL_WIDTH)).toBe(panelHalfWidth);
+  });
+  (0, _vitest.it)('패널이 오른쪽으로 밀린 경우(왼쪽 경계 클램핑) 화살표는 왼쪽으로 이동해 앵커를 가리킨다', () => {
+    const anchorCenterX = 60;
+    const expectedOffset = 52; // 60 - 8
+    (0, _vitest.expect)((0, _utils.calculateArrowOffsetX)(anchorCenterX, CLAMPED_LEFT, PANEL_WIDTH)).toBe(expectedOffset);
+  });
+  (0, _vitest.it)('패널이 왼쪽으로 밀린 경우(오른쪽 경계 클램핑) 화살표는 오른쪽으로 이동해 앵커를 가리킨다', () => {
+    const anchorCenterX = 950;
+    const clampedRightPanelLeft = 692;
+    const expectedOffset = 258; // 950 - 692
+    (0, _vitest.expect)((0, _utils.calculateArrowOffsetX)(anchorCenterX, clampedRightPanelLeft, PANEL_WIDTH)).toBe(expectedOffset);
+  });
+  (0, _vitest.it)('앵커가 패널 왼쪽 모서리보다 바깥이면 최소 여백(모서리 radius + 화살표)으로 클램핑한다', () => {
+    const outsideLeftAnchorX = 10;
+    (0, _vitest.expect)((0, _utils.calculateArrowOffsetX)(outsideLeftAnchorX, CLAMPED_LEFT, PANEL_WIDTH)).toBe(_utils.ARROW_EDGE_MARGIN);
+  });
+  (0, _vitest.it)('앵커가 패널 오른쪽 모서리보다 바깥이면 최대 여백으로 클램핑한다', () => {
+    const outsideRightAnchorX = 999;
+    (0, _vitest.expect)((0, _utils.calculateArrowOffsetX)(outsideRightAnchorX, CLAMPED_LEFT, PANEL_WIDTH)).toBe(PANEL_WIDTH - _utils.ARROW_EDGE_MARGIN);
+  });
+  (0, _vitest.it)('소수 좌표는 반올림한다', () => {
+    const fractionalAnchorX = 100.4;
+    const panelLeft = 50;
+    const expectedRounded = 50; // 100.4 - 50 = 50.4 → 50
+    (0, _vitest.expect)((0, _utils.calculateArrowOffsetX)(fractionalAnchorX, panelLeft, PANEL_WIDTH)).toBe(expectedRounded);
+  });
+});

package/dist/cjs/src/components/overlays/tooltip/utils.js

@@ -0,0 +1,20 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.ARROW_EDGE_MARGIN = void 0;
+exports.calculateArrowOffsetX = calculateArrowOffsetX;
+// 화살표가 패널 모서리(border-radius 6px + 화살표 반너비 6px) 안쪽으로 파고들지 않기 위한 최소 여백
+const ARROW_EDGE_MARGIN = exports.ARROW_EDGE_MARGIN = 12;
+/**
+ * top/bottom 툴팁 화살표(::after)의 패널 내 X 오프셋.
+ * 패널이 viewport 경계 보정으로 앵커 중심에서 밀려도 화살표는 앵커를 가리키도록,
+ * 클램핑된 패널 left 기준으로 앵커 중심까지의 거리를 계산한다.
+ * 앵커가 패널 밖에 있으면 패널 모서리 여백까지만 이동한다.
+ * React(Tooltip.tsx)와 HTML 구현체(assets/scripts/tooltip)가 공유한다.
+ */
+function calculateArrowOffsetX(anchorCenterX, panelLeft, panelWidth) {
+  const raw = anchorCenterX - panelLeft;
+  return Math.round(Math.max(ARROW_EDGE_MARGIN, Math.min(raw, panelWidth - ARROW_EDGE_MARGIN)));
+}

package/dist/cjs/src/hooks/index.js

@@ -36,6 +36,17 @@ Object.keys(_useFloatingPosition).forEach(function (key) {
     }
   });
 });
+var _useIsomorphicLayoutEffect = require("./useIsomorphicLayoutEffect");
+Object.keys(_useIsomorphicLayoutEffect).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _useIsomorphicLayoutEffect[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _useIsomorphicLayoutEffect[key];
+    }
+  });
+});
 var _useMediaQuery = require("./useMediaQuery");
 Object.keys(_useMediaQuery).forEach(function (key) {
   if (key === "default" || key === "__esModule") return;

package/dist/cjs/src/hooks/useIsomorphicLayoutEffect.js

@@ -0,0 +1,8 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useIsomorphicLayoutEffect = void 0;
+var _react = require("react");
+const useIsomorphicLayoutEffect = exports.useIsomorphicLayoutEffect = typeof window !== 'undefined' ? _react.useLayoutEffect : _react.useEffect;

package/dist/cjs/src/hooks/useMediaQuery.js

@@ -20,6 +20,9 @@ const useMediaQuery = (query, options) => {
     return () => {
       mediaQuery.removeEventListener('change', handleChange);
     };
+    // options 객체 전체가 아니라 실제 사용하는 onMatched 콜백에만 의존한다. options 를 통째로
+    // 넣으면 매 렌더 새 객체로 간주돼 불필요하게 재구독한다.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [query, options?.onMatched]);
   return matches;
 };

package/dist/cjs/src/utils/__tests__/date-picker.test.js

@@ -0,0 +1,29 @@
+"use strict";
+
+var _moment = _interopRequireDefault(require("moment"));
+var _vitest = require("vitest");
+var _datePicker = require("../date-picker");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+(0, _vitest.describe)('convertToMomentFormat', () => {
+  (0, _vitest.it)('날짜 전용 포맷을 moment 토큰으로 변환한다 (기존 동작 보존)', () => {
+    (0, _vitest.expect)((0, _datePicker.convertToMomentFormat)('Y-m-d')).toBe('YYYY-MM-DD');
+  });
+  (0, _vitest.it)('2자리 연도(y)를 YY로 변환한다', () => {
+    (0, _vitest.expect)((0, _datePicker.convertToMomentFormat)('y-m-d')).toBe('YY-MM-DD');
+  });
+  (0, _vitest.it)('시간 포함 포맷의 H/i/S를 모두 변환한다 (버그 수정 지점)', () => {
+    (0, _vitest.expect)((0, _datePicker.convertToMomentFormat)('Y-m-d H:i')).toBe('YYYY-MM-DD HH:mm');
+    (0, _vitest.expect)((0, _datePicker.convertToMomentFormat)('Y-m-d H:i:S')).toBe('YYYY-MM-DD HH:mm:ss');
+  });
+  (0, _vitest.it)('월(m)과 분(i)이 함께 있어도 서로 침범하지 않는다', () => {
+    // m -> MM(월) 먼저, i -> mm(분) 나중 순서가 지켜져야 함
+    (0, _vitest.expect)((0, _datePicker.convertToMomentFormat)('Y-m-d H:i')).not.toContain('i');
+    (0, _vitest.expect)((0, _datePicker.convertToMomentFormat)('Y-m-d H:i')).toBe('YYYY-MM-DD HH:mm');
+  });
+  (0, _vitest.it)('실제 moment 출력이 의도한 문자열과 일치한다 (회귀 핵심)', () => {
+    const date = (0, _moment.default)('2024-03-20 14:30:05', 'YYYY-MM-DD HH:mm:ss').toDate();
+    (0, _vitest.expect)((0, _moment.default)(date).format((0, _datePicker.convertToMomentFormat)('Y-m-d'))).toBe('2024-03-20');
+    (0, _vitest.expect)((0, _moment.default)(date).format((0, _datePicker.convertToMomentFormat)('Y-m-d H:i'))).toBe('2024-03-20 14:30');
+    (0, _vitest.expect)((0, _moment.default)(date).format((0, _datePicker.convertToMomentFormat)('Y-m-d H:i:S'))).toBe('2024-03-20 14:30:05');
+  });
+});

package/dist/cjs/src/utils/date-picker.js

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.formatMinuteInput = exports.formatHourInput = exports.formatDateInput = void 0;
+exports.formatMinuteInput = exports.formatHourInput = exports.formatDateInput = exports.convertToMomentFormat = void 0;
 exports.getDateFormat = getDateFormat;
 exports.getSubtractDate = getSubtractDate;
 exports.getToday = getToday;
@@ -31,6 +31,20 @@ function getSubtractDate(_ref) {
   } = _ref;
   return (0, _moment.default)(date).subtract(period, unit).toDate();
 }
+/** flatpickr dateFormat 토큰을 moment 포맷 토큰으로 변환 (단일 패스 치환으로 토큰 간 간섭 방지) */
+const convertToMomentFormat = format => {
+  const tokenMap = {
+    Y: 'YYYY',
+    y: 'YY',
+    m: 'MM',
+    d: 'DD',
+    H: 'HH',
+    i: 'mm',
+    S: 'ss'
+  };
+  return format.replace(/[YymdHiS]/g, matched => tokenMap[matched] || matched);
+};
+exports.convertToMomentFormat = convertToMomentFormat;
 const formatDateInput = input => {
   const dateRegex = /^(19|20)\d{2}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[0-1])$/;
   if (dateRegex.test(input)) {

package/dist/esm/src/components/forms-and-input/checkbox/CheckboxInput.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import classNames from 'classnames';
-import { forwardRef, useEffect, useRef } from 'react';
+import { forwardRef, useRef } from 'react';
+import { useIsomorphicLayoutEffect } from '../../../hooks/useIsomorphicLayoutEffect';
 export const CheckboxInput = /*#__PURE__*/forwardRef((_ref, ref) => {
   let {
     size = 'xs',
@@ -12,10 +13,10 @@ export const CheckboxInput = /*#__PURE__*/forwardRef((_ref, ref) => {
     ...props
   } = _ref;
   const inputRef = useRef(null);
-  useEffect(() => {
+  useIsomorphicLayoutEffect(() => {
     const input = ref && typeof ref !== 'function' ? ref.current : inputRef.current;
     if (input) {
-      input.indeterminate = indeterminate; // 외부에서 받은 값을 그대로 사용
+      input.indeterminate = indeterminate;
     }
   }, [indeterminate, ref]);
   return _jsx("span", {

package/dist/esm/src/components/forms-and-input/date-picker/DatePicker.js

@@ -4,7 +4,7 @@ import { Korean } from 'flatpickr/dist/l10n/ko';
 import moment from 'moment';
 import { forwardRef, useCallback, useEffect, useId, useMemo, useRef } from 'react';
 import Flatpickr from 'react-flatpickr';
-import { formatDateInput, formatHourInput, formatMinuteInput } from '../../../utils/date-picker';
+import { convertToMomentFormat, formatDateInput, formatHourInput, formatMinuteInput } from '../../../utils/date-picker';
 import { CustomInput } from './CustomInput';
 // ══════════════════════════════════════════
 // 유틸리티 함수
@@ -176,6 +176,12 @@ const setupTimeInputHandlers = (instance, input, isPortal, onHourInput, onMinute
 };
 /** 시간 입력 필드 이벤트 리스너 정리 */
 const cleanupTimeInputHandlers = (instance, input, isPortal, onHourInput, onMinuteInput) => {
+  // document 전역 리스너는 캘린더 DOM 조회 성공 여부와 무관하게 항상 먼저 제거한다 (누수 방지)
+  const handleMouseDown = instance._handleMouseDown;
+  if (handleMouseDown) {
+    document.removeEventListener('mousedown', handleMouseDown, true);
+    instance._handleMouseDown = undefined;
+  }
   const timeContainer = isPortal ? instance.calendarContainer : input.parentElement;
   const timeInputWrapper = timeContainer?.querySelector('.flatpickr-time');
   if (!timeInputWrapper) return;
@@ -187,10 +193,6 @@ const cleanupTimeInputHandlers = (instance, input, isPortal, onHourInput, onMinu
   if (minuteInput) {
     minuteInput.removeEventListener('input', onMinuteInput);
   }
-  const handleMouseDown = instance._handleMouseDown;
-  if (handleMouseDown) {
-    document.removeEventListener('mousedown', handleMouseDown, true);
-  }
 };
 // ══════════════════════════════════════════
 // DatePicker 컴포넌트
@@ -220,7 +222,7 @@ export const DatePicker = /*#__PURE__*/forwardRef((_ref, ref) => {
   const onValidationErrorRef = useRef(onValidationError);
   onValidationErrorRef.current = onValidationError;
   /** portal 컨테이너를 lazily 생성 (이미 있으면 재사용), className은 매번 갱신 */
-  const getPortalContainer = () => {
+  const getPortalContainer = useCallback(() => {
     if (!portal || typeof document === 'undefined') return undefined;
     const portalClassName = classNames('ncua-date-picker', 'ncua-date-picker--portal', `ncua-date-picker--${size}`, {
       'ncua-date-picker--has-time': hasTimeOption
@@ -236,7 +238,7 @@ export const DatePicker = /*#__PURE__*/forwardRef((_ref, ref) => {
     document.body.appendChild(el);
     portalContainerRef.current = el;
     return el;
-  };
+  }, [portal, size, hasTimeOption]);
   /** 컴포넌트 언마운트 시 포탈 컨테이너 및 스크롤 리스너 정리 */
   useEffect(() => {
     return () => {
@@ -248,7 +250,7 @@ export const DatePicker = /*#__PURE__*/forwardRef((_ref, ref) => {
   // 날짜 유효성 검사
   // ──────────────────────────────────────────────
   /** minDate/maxDate 범위를 벗어났는지 확인 */
-  const checkDateViolations = (date, minDate, maxDate) => {
+  const checkDateViolations = useCallback((date, minDate, maxDate) => {
     const violations = [];
     const inputDate = moment(date);
     if (!inputDate.isValid()) return violations;
@@ -265,16 +267,16 @@ export const DatePicker = /*#__PURE__*/forwardRef((_ref, ref) => {
       }
     }
     return violations;
-  };
+  }, []);
   // ──────────────────────────────────────────────
   // 이벤트 핸들러
   // ──────────────────────────────────────────────
   /** 유효하지 않은 입력 시 이전 날짜로 복원 */
-  const restorePreviousDate = (target, instance) => {
+  const restorePreviousDate = useCallback((target, instance) => {
     if (instance.selectedDates.length > 0) {
       const prevDate = instance.selectedDates[0];
       if (prevDate instanceof Date && !Number.isNaN(prevDate.getTime())) {
-        const momentFormat = dateFormatRef.current.replace(/Y/g, 'YYYY').replace(/m/g, 'MM').replace(/d/g, 'DD');
+        const momentFormat = convertToMomentFormat(dateFormatRef.current);
         target.value = moment(prevDate).format(momentFormat);
         instance.setDate(prevDate, false);
         return;
@@ -282,7 +284,7 @@ export const DatePicker = /*#__PURE__*/forwardRef((_ref, ref) => {
     }
     target.value = '';
     instance.setDate('', false);
-  };
+  }, []);
   /** flatpickr에서 날짜가 변경되었을 때 호출 */
   const onChangeDateHandler = useCallback((dateTimeStamp, dateStr, fpInstance) => {
     const instance = fpInstance;
@@ -296,7 +298,9 @@ export const DatePicker = /*#__PURE__*/forwardRef((_ref, ref) => {
     const maxDate = instance.config.maxDate;
     const violations = checkDateViolations(selectedDate, minDate, maxDate);
     if (violations.length > 0 && onValidationErrorRef.current) {
-      const prevDate = instance?.selectedDates?.[0];
+      // flatpickr는 onChange 발화 전에 selectedDates를 위반된 새 날짜로 갱신하므로,
+      // 직전 유효 날짜를 보관해 둔 _previousDateBeforeInput을 previousDate로 사용한다
+      const prevDate = instance._previousDateBeforeInput;
       const validPrevDate = prevDate instanceof Date && !Number.isNaN(prevDate.getTime()) ? prevDate : undefined;
       onValidationErrorRef.current({
         date: selectedDate,
@@ -312,7 +316,6 @@ export const DatePicker = /*#__PURE__*/forwardRef((_ref, ref) => {
     isValidDate(formattedDate) ? onChangeDateRef.current(formattedDate) : onChangeDateRef.current(dateStr);
   }, [checkDateViolations, restorePreviousDate]);
   /** input에 직접 타이핑할 때 날짜 형식 자동 변환 및 유효성 검사 */
-  // eslint-disable-next-line react-hooks/exhaustive-deps
   const onInputHandler = useCallback(e => {
     const target = e.target;
     const input = target.value;
@@ -365,12 +368,6 @@ export const DatePicker = /*#__PURE__*/forwardRef((_ref, ref) => {
   // ──────────────────────────────────────────────
   // flatpickr 옵션
   // ──────────────────────────────────────────────
-  // datePickerOptions는 부모에서 매 렌더 새 객체일 수 있으므로 값 기반 비교
-  // 주의: JSON.stringify는 함수를 무시하고 Date를 문자열로 변환하므로,
-  // datePickerOptions에 함수나 Date 객체를 넘기면 변경 감지가 누락될 수 있음
-  // eslint-disable-next-line react-hooks/exhaustive-deps
-  const _datePickerOptionsKey = JSON.stringify(datePickerOptions);
-  // eslint-disable-next-line react-hooks/exhaustive-deps
   const options = useMemo(() => ({
     mode: 'single',
     static: !portal,
@@ -391,7 +388,7 @@ export const DatePicker = /*#__PURE__*/forwardRef((_ref, ref) => {
         if (!momentDate.isValid()) {
           return '';
         }
-        const momentFormat = format.replace(/Y/g, 'YYYY').replace(/y/g, 'YY').replace(/m/g, 'MM').replace(/d/g, 'DD').replace(/H/g, 'HH').replace(/i/g, 'mm').replace(/S/g, 'ss');
+        const momentFormat = convertToMomentFormat(format);
         return momentDate.format(momentFormat);
       } catch (_error) {
         return '';

package/dist/esm/src/components/forms-and-input/date-picker/__tests__/DatePicker.memo.test.js

@@ -0,0 +1,50 @@
+// @vitest-environment jsdom
+import { createElement, useState } from 'react';
+import { createRoot } from 'react-dom/client';
+import { act } from 'react-dom/test-utils';
+import { describe, expect, it, vi } from 'vitest';
+import { DatePicker } from '../DatePicker';
+const {
+  captured
+} = vi.hoisted(() => ({
+  captured: []
+}));
+// react-flatpickr를 mock하여 DatePicker가 넘기는 options 참조를 렌더마다 수집한다.
+// (vi.mock / vi.hoisted는 vitest가 import 위로 호이스팅하므로 DatePicker import보다 먼저 적용된다)
+vi.mock('react-flatpickr', () => ({
+  default: props => {
+    captured.push(props.options);
+    return null;
+  }
+}));
+describe('#1 options useMemo 안정성', () => {
+  it('부모가 같은 props로 강제 리렌더해도 options 참조가 동일하게 유지된다(재생성 안 됨)', () => {
+    let bump = () => undefined;
+    const Harness = () => {
+      const [, setN] = useState(0);
+      bump = () => setN(x => x + 1);
+      return /*#__PURE__*/createElement(DatePicker, {
+        currentDate: '2024-03-20',
+        onChangeDate: () => undefined
+      });
+    };
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    const root = createRoot(container);
+    act(() => {
+      root.render(/*#__PURE__*/createElement(Harness));
+    });
+    const countAfterMount = captured.length;
+    const firstOptions = captured[captured.length - 1];
+    act(() => {
+      bump();
+    });
+    const lastOptions = captured[captured.length - 1];
+    expect(captured.length).toBeGreaterThan(countAfterMount); // 리렌더가 실제로 일어났는지
+    expect(Object.is(firstOptions, lastOptions)).toBe(true); // 동일 참조 = options 재생성 안 됨
+    act(() => {
+      root.unmount();
+    });
+    container.remove();
+  });
+});

package/dist/esm/src/components/forms-and-input/date-picker/__tests__/DatePicker.test.js

@@ -0,0 +1,126 @@
+// @vitest-environment jsdom
+import { createElement } from 'react';
+import { createRoot } from 'react-dom/client';
+import { act } from 'react-dom/test-utils';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { DatePicker } from '../DatePicker';
+const mounted = [];
+function mount(props) {
+  const container = document.createElement('div');
+  document.body.appendChild(container);
+  const root = createRoot(container);
+  act(() => {
+    root.render(/*#__PURE__*/createElement(DatePicker, props));
+  });
+  mounted.push({
+    root,
+    container
+  });
+  return container;
+}
+afterEach(() => {
+  for (const {
+    root,
+    container
+  } of mounted.splice(0)) {
+    act(() => {
+      root.unmount();
+    });
+    container.remove();
+  }
+  vi.restoreAllMocks();
+});
+describe('DatePicker 렌더 (스모크)', () => {
+  it('기본 props로 input을 렌더하고 크래시하지 않는다', () => {
+    const container = mount({
+      currentDate: '2024-03-20',
+      onChangeDate: () => undefined
+    });
+    expect(container.querySelector('input')).not.toBeNull();
+  });
+  it('enableTime 옵션으로도 정상 렌더한다', () => {
+    const container = mount({
+      currentDate: '2024-03-20 14:30',
+      onChangeDate: () => undefined,
+      datePickerOptions: {
+        enableTime: true,
+        dateFormat: 'Y-m-d H:i'
+      }
+    });
+    expect(container.querySelector('input')).not.toBeNull();
+  });
+});
+describe('#4 document mousedown 리스너 정리', () => {
+  it('enableTime 마운트 후 언마운트 시, 추가된 mousedown 리스너가 모두 제거된다(누수 없음)', () => {
+    const added = [];
+    const removed = [];
+    const origAdd = document.addEventListener.bind(document);
+    const origRemove = document.removeEventListener.bind(document);
+    vi.spyOn(document, 'addEventListener').mockImplementation((type, fn, opts) => {
+      if (type === 'mousedown' && fn) added.push(fn);
+      return origAdd(type, fn, opts);
+    });
+    vi.spyOn(document, 'removeEventListener').mockImplementation((type, fn, opts) => {
+      if (type === 'mousedown' && fn) removed.push(fn);
+      return origRemove(type, fn, opts);
+    });
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    const root = createRoot(container);
+    act(() => {
+      root.render(/*#__PURE__*/createElement(DatePicker, {
+        currentDate: '2024-03-20 14:30',
+        onChangeDate: () => undefined,
+        datePickerOptions: {
+          enableTime: true,
+          dateFormat: 'Y-m-d H:i'
+        }
+      }));
+    });
+    expect(added.length).toBeGreaterThanOrEqual(1);
+    act(() => {
+      root.unmount();
+    });
+    container.remove();
+    for (const fn of added) {
+      expect(removed).toContain(fn);
+    }
+  });
+});
+describe('#3 onValidationError.previousDate', () => {
+  // 허용 범위(10~25일) 기준: 마지막 유효 선택일과 범위 밖 위반일
+  const LAST_VALID_DAY = 15;
+  const OUT_OF_RANGE_DAY = 30;
+  it('min/max 위반 시 previousDate는 위반 날짜가 아니라 직전 유효 날짜다', () => {
+    const onValidationError = vi.fn();
+    const container = mount({
+      currentDate: '2024-03-20',
+      onChangeDate: () => undefined,
+      datePickerOptions: {
+        minDate: '2024-03-10',
+        maxDate: '2024-03-25',
+        allowInput: true
+      },
+      onValidationError
+    });
+    // flatpickr 인스턴스는 초기화된 input 엘리먼트의 _flatpickr에 부착된다
+    const input = container.querySelector('input');
+    const instance = input?._flatpickr;
+    expect(instance).toBeTruthy();
+    // 1) 유효 날짜를 먼저 선택 → 직전 유효값(_previousDateBeforeInput)이 확립됨
+    act(() => {
+      instance.setDate(`2024-03-${LAST_VALID_DAY}`, true);
+    });
+    expect(onValidationError).not.toHaveBeenCalled();
+    // 2) 허용 범위 밖 날짜 선택 → 위반 분기 진입
+    act(() => {
+      instance.setDate(`2024-03-${OUT_OF_RANGE_DAY}`, true);
+    });
+    expect(onValidationError).toHaveBeenCalledTimes(1);
+    const arg = onValidationError.mock.calls[0][0];
+    expect(arg.violations).toContain('maxDate');
+    expect(arg.date.getDate()).toBe(OUT_OF_RANGE_DAY); // 위반 날짜
+    expect(arg.previousDate?.getDate()).toBe(LAST_VALID_DAY); // 직전 유효 날짜 (≠ 위반 날짜)
+    expect(arg.previousDate?.getTime()).not.toBe(arg.date.getTime());
+  });
+});