@ncds/ui-admin 1.8.16 → 1.8.18

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

@@ -51,6 +51,23 @@ const restoreIfInvalidDate = (date, instance) => {
   }
   return true;
 };
+/** Date 를 dateFormat 표기 문자열로 바꾼다. 유효하지 않으면 null. */
+const formatSelectedDate = (selectedDate, dateFormat) => {
+  if (!(selectedDate instanceof Date) || Number.isNaN(selectedDate.getTime())) return null;
+  const formattedDate = moment(selectedDate).format(convertToMomentFormat(dateFormat));
+  return formattedDate || null;
+};
+/** 'YYYY-MM-DD' 길이. dateFormat 을 읽기 전(onReady 이전)의 기본값이다 */
+const FULL_DATE_LENGTH = 10;
+/** 연·월·일·시·분·초가 모두 두 자리 이상인 기준 시각. 길이 측정용이라 날짜 값 자체에 의미는 없다 */
+const FULL_VALUE_REFERENCE_DATE = '2026-03-01 04:05:06';
+/**
+ * 해당 dateFormat 으로 완성된 값의 길이. 'Y-m-d'=10, 'Y-m-d H:i'=16, 'H:i'=5.
+ *
+ * 완성 판정을 10 으로 고정하면 enableTime(16자) 에서 아직 덜 친 중간 상태를 완성으로 오판한다.
+ * 그러면 `2026-03-01 0` 같은 값이 유효성 검사에 걸려 입력이 통째로 이전 값으로 되돌아간다.
+ */
+const getFullValueLength = dateFormat => moment(FULL_VALUE_REFERENCE_DATE).format(convertToMomentFormat(dateFormat)).length || FULL_DATE_LENGTH;
 /** 시간 전용 모드의 기본값 반환 */
 const getTimeOnlyDefault = (hasSeconds, isEndDate) => {
   const endTime = hasSeconds ? '23:59:59' : '23:59';
@@ -212,7 +229,10 @@ export const DatePicker = /*#__PURE__*/forwardRef((_ref, ref) => {
   } = _ref;
   const flatpickrInstanceRef = useRef(null);
   const dateFormatRef = useRef('Y-m-d');
-  const minMaxDateRef = useRef({});
+  /** 현재 dateFormat 기준 완성 값의 길이 (getFullValueLength 주석 참고) */
+  const fullValueLengthRef = useRef(FULL_DATE_LENGTH);
+  /** 인스턴스 파괴 직전에 input 이 포커스를 쥐고 있었는지 */
+  const hadFocusBeforeDestroyRef = useRef(false);
   /** portal 모드: 캘린더를 담을 persistent 컨테이너 (한 번 생성, 언마운트 시 제거) */
   const portalContainerRef = useRef(null);
   const hasTimeOption = datePickerOptions && Object.hasOwn(datePickerOptions, 'enableTime');
@@ -221,6 +241,12 @@ export const DatePicker = /*#__PURE__*/forwardRef((_ref, ref) => {
   onChangeDateRef.current = onChangeDate;
   const onValidationErrorRef = useRef(onValidationError);
   onValidationErrorRef.current = onValidationError;
+  /** flatpickr에 실제로 로드된 날짜 문자열. onReady 클로저는 최초 렌더 값에 고정되므로 ref로 최신값을 본다 */
+  const loadedDateRef = useRef('');
+  /** 마지막으로 부모에 통지한 날짜. blur 동기화의 중복 통지를 막는다 */
+  const lastNotifiedDateRef = useRef(null);
+  /** blur 동기화 지연 타이머 */
+  const blurSyncTimerRef = useRef(null);
   /** portal 컨테이너를 lazily 생성 (이미 있으면 재사용), className은 매번 갱신 */
   const getPortalContainer = useCallback(() => {
     if (!portal || typeof document === 'undefined') return undefined;
@@ -239,11 +265,15 @@ export const DatePicker = /*#__PURE__*/forwardRef((_ref, ref) => {
     portalContainerRef.current = el;
     return el;
   }, [portal, size, hasTimeOption]);
-  /** 컴포넌트 언마운트 시 포탈 컨테이너 및 스크롤 리스너 정리 */
+  /** 컴포넌트 언마운트 시 포탈 컨테이너 및 지연 타이머 정리 */
   useEffect(() => {
     return () => {
       portalContainerRef.current?.remove();
       portalContainerRef.current = null;
+      if (blurSyncTimerRef.current) {
+        clearTimeout(blurSyncTimerRef.current);
+        blurSyncTimerRef.current = null;
+      }
     };
   }, []);
   // ──────────────────────────────────────────────
@@ -285,6 +315,66 @@ export const DatePicker = /*#__PURE__*/forwardRef((_ref, ref) => {
     target.value = '';
     instance.setDate('', false);
   }, []);
+  /**
+   * 부모가 이미 그 값을 알고 있으면 true — 통지할 것이 없다.
+   *
+   * flatpickr 는 값을 확정하는 경로가 4개(캘린더 선택·Enter·타이핑·바깥클릭)이고 서로의 실행을
+   * 모른다. 그래서 같은 값이 여러 경로에서 중복 통지되기 쉬운데, 판정을 이 한 곳에만 둔다.
+   * - loadedDate: 부모가 prop 으로 들고 있는 값과 같으면 바뀐 게 없다
+   * - lastNotifiedDate: 부모가 state 를 갱신하지 않는 사용처(uncontrolled)에서도 중복을 막는다
+   */
+  const isAlreadyNotified = useCallback(nextDate => nextDate === loadedDateRef.current || nextDate === lastNotifiedDateRef.current, []);
+  /**
+   * 부모로 날짜를 통지하는 유일한 창구. 통지했으면 true.
+   * lastNotifiedDateRef 를 쓰는 곳도 여기 하나뿐이다.
+   */
+  const commitDate = useCallback(nextDate => {
+    if (isAlreadyNotified(nextDate)) return false;
+    lastNotifiedDateRef.current = nextDate;
+    onChangeDateRef.current(nextDate);
+    return true;
+  }, [isAlreadyNotified]);
+  /**
+   * min/max 위반이면 onValidationError 로 보고하고 true(통지 중단)를 반환한다.
+   * 캘린더 선택 경로(onChangeDateHandler)와 동일한 방어를 blur 동기화에도 적용하기 위한 것으로,
+   * 이 검사가 없으면 범위 밖 날짜를 타이핑한 뒤 마우스로 빠져나갈 때 방어가 뚫린다.
+   */
+  const reportViolationIfAny = useCallback((selectedDate, instance, previousDate) => {
+    const minDate = instance.config.minDate;
+    const maxDate = instance.config.maxDate;
+    const violations = checkDateViolations(selectedDate, minDate, maxDate);
+    if (violations.length === 0 || !onValidationErrorRef.current) return false;
+    const validPreviousDate = previousDate instanceof Date && !Number.isNaN(previousDate.getTime()) ? previousDate : undefined;
+    onValidationErrorRef.current({
+      date: selectedDate,
+      minDate,
+      maxDate,
+      violations,
+      previousDate: validPreviousDate
+    });
+    return true;
+  }, [checkDateViolations]);
+  /**
+   * blur 이후 flatpickr가 끝내 통지하지 않은 값을 부모로 올린다.
+   *
+   * flatpickr는 경로마다 onChange 발화 시점이 다르다. Enter/Tab 은 blur 보다 앞이고, 캘린더 선택은
+   * blur 보다 뒤다. 그래서 blur 시점에 동기적으로 판정하면 어느 한쪽이 반드시 중복 통지된다.
+   * 한 틱 미뤄 "결국 아무도 통지하지 않은 경우"만 남겨서 처리한다.
+   */
+  const scheduleBlurSync = useCallback(previousDate => {
+    if (blurSyncTimerRef.current) clearTimeout(blurSyncTimerRef.current);
+    blurSyncTimerRef.current = setTimeout(() => {
+      blurSyncTimerRef.current = null;
+      const instance = flatpickrInstanceRef.current;
+      if (!instance || instance.selectedDates.length === 0) return;
+      const selectedDate = instance.selectedDates[0];
+      const dateToNotify = formatSelectedDate(selectedDate, dateFormatRef.current);
+      // 바뀐 게 없으면 위반 보고도 하지 않는다. 안 그러면 blur 마다 알럿이 반복된다
+      if (dateToNotify === null || isAlreadyNotified(dateToNotify)) return;
+      if (reportViolationIfAny(selectedDate, instance, previousDate)) return;
+      commitDate(dateToNotify);
+    }, 0);
+  }, [commitDate, isAlreadyNotified, reportViolationIfAny]);
   /** flatpickr에서 날짜가 변경되었을 때 호출 */
   const onChangeDateHandler = useCallback((dateTimeStamp, dateStr, fpInstance) => {
     const instance = fpInstance;
@@ -294,27 +384,38 @@ export const DatePicker = /*#__PURE__*/forwardRef((_ref, ref) => {
     }
     if (restoreIfInvalidDate(dateTimeStamp[0], instance)) return;
     const selectedDate = dateTimeStamp[0];
-    const minDate = instance.config.minDate;
-    const maxDate = instance.config.maxDate;
-    const violations = checkDateViolations(selectedDate, minDate, maxDate);
-    if (violations.length > 0 && onValidationErrorRef.current) {
-      // flatpickr는 onChange 발화 전에 selectedDates를 위반된 새 날짜로 갱신하므로,
-      // 직전 유효 날짜를 보관해 둔 _previousDateBeforeInput을 previousDate로 사용한다
-      const prevDate = instance._previousDateBeforeInput;
-      const validPrevDate = prevDate instanceof Date && !Number.isNaN(prevDate.getTime()) ? prevDate : undefined;
-      onValidationErrorRef.current({
-        date: selectedDate,
-        minDate,
-        maxDate,
-        violations,
-        previousDate: validPrevDate
-      });
-      return;
-    }
+    // flatpickr는 onChange 발화 전에 selectedDates를 위반된 새 날짜로 갱신하므로,
+    // 직전 유효 날짜를 보관해 둔 _previousDateBeforeInput을 previousDate로 넘긴다
+    if (reportViolationIfAny(selectedDate, instance, instance._previousDateBeforeInput)) return;
     instance._previousDateBeforeInput = selectedDate;
     const formattedDate = formatDateInput(dateStr);
-    isValidDate(formattedDate) ? onChangeDateRef.current(formattedDate) : onChangeDateRef.current(dateStr);
-  }, [checkDateViolations, restorePreviousDate]);
+    commitDate(isValidDate(formattedDate) ? formattedDate : dateStr);
+  }, [commitDate, reportViolationIfAny, restorePreviousDate]);
+  /**
+   * 타이핑으로 완성된 날짜를 blur 를 기다리지 않고 즉시 부모로 올린다. 통지했으면 true.
+   *
+   * blur 까지 미루면, 타이핑 중 부모 리렌더가 한 번이라도 끼는 순간 react-flatpickr 의
+   * "value !== input.value 면 setDate(value, false)" effect 가 타이핑 값을 부모가 들고 있던
+   * 값으로 되돌려 버린다. 그러면 blur 시점에는 바뀐 게 없다고 판정돼 onChangeDate 도,
+   * 뒤이은 범위 검증(onDateValidation)도 돌지 않는다. (#410 재보고분)
+   */
+  const notifyTypedDate = useCallback((instance, formattedInput) => {
+    const typedDate = moment(formattedInput, convertToMomentFormat(dateFormatRef.current), true).toDate();
+    // min/max 는 instance.config 를 단일 소스로 쓴다. onReady 시점 값을 ref 에 담아두면,
+    // 부모가 minDate/maxDate 를 바꿨을 때 타이핑 경로와 blur/캘린더 경로의 판정이 갈릴 수 있다
+    const violations = checkDateViolations(typedDate, instance.config.minDate, instance.config.maxDate);
+    // 범위 위반은 타이핑 중에 보고하지 않는다 — 한 글자마다 알럿이 뜬다.
+    // 입력을 마치고 빠져나갈 때 scheduleBlurSync 의 reportViolationIfAny 가 한 번만 보고한다.
+    if (violations.length > 0) return false;
+    const dateToNotify = formatSelectedDate(typedDate, dateFormatRef.current);
+    // 입력 문자열이 이미 최종 표기와 같을 때만 통지한다. 다르면(예: enableTime 인데 시간을
+    // 아직 안 친 상태) 아래 setDate 가 input 값을 다시 써서 타이핑 중 커서가 튄다.
+    // 그 경우는 종전대로 blur 시점 동기화에 맡긴다.
+    if (dateToNotify === null || dateToNotify !== formattedInput) return false;
+    if (isAlreadyNotified(dateToNotify)) return false;
+    instance.setDate(typedDate, false);
+    return commitDate(dateToNotify);
+  }, [checkDateViolations, commitDate, isAlreadyNotified]);
   /** input에 직접 타이핑할 때 날짜 형식 자동 변환 및 유효성 검사 */
   const onInputHandler = useCallback(e => {
     const target = e.target;
@@ -324,7 +425,7 @@ export const DatePicker = /*#__PURE__*/forwardRef((_ref, ref) => {
     if (!input?.trim()) {
       target.value = '';
       instance.setDate('', false);
-      onChangeDateRef.current('');
+      commitDate('');
       return;
     }
     if (!/[0-9]/.test(input)) {
@@ -333,21 +434,20 @@ export const DatePicker = /*#__PURE__*/forwardRef((_ref, ref) => {
     }
     const formattedInput = formatDateInput(input);
     if (formattedInput !== input) {
+      // 여기서 멈추지 않는다. 8자리 숫자를 다 치거나 붙여넣으면 이 시점에 이미 완성된
+      // 날짜이고, 우리가 다시 쓴 값에 대해 브라우저는 input 이벤트를 더 주지 않는다.
       target.value = formattedInput;
-      return;
     }
-    if (!formattedInput || formattedInput.length < 10) return;
-    const parsedDate = moment(formattedInput);
-    if (!parsedDate.isValid()) {
+    // 완성 전에는 검증하지 않는다. 중간 상태를 완성으로 오판하면 아래에서 입력이 되돌아간다
+    if (formattedInput.length < fullValueLengthRef.current) return;
+    // 포맷을 넘겨 strict 로 파싱한다. 포맷 없이 moment(값) 만 쓰면 시간 전용 모드의
+    // '14:30' 같은 값을 파싱하지 못해 정상 입력이 되돌려진다
+    if (!moment(formattedInput, convertToMomentFormat(dateFormatRef.current), true).isValid()) {
       restorePreviousDate(target, instance);
       return;
     }
-    const parsedDateObj = parsedDate.toDate();
-    const violations = checkDateViolations(parsedDateObj, minMaxDateRef.current.minDate, minMaxDateRef.current.maxDate);
-    if (violations.length > 0) {
-      return;
-    }
-  }, [checkDateViolations, restorePreviousDate]);
+    notifyTypedDate(instance, formattedInput);
+  }, [commitDate, notifyTypedDate, restorePreviousDate]);
   /** 시간 입력 필드 - 시(hour) 값 포맷팅 (0~23) */
   const onHourInputHandler = useCallback(e => {
     const target = e.target;
@@ -405,15 +505,16 @@ export const DatePicker = /*#__PURE__*/forwardRef((_ref, ref) => {
       if (!input) return;
       flatpickrInstanceRef.current = instance;
       dateFormatRef.current = instance.config.dateFormat || 'Y-m-d';
-      minMaxDateRef.current = {
-        minDate: instance.config.minDate,
-        maxDate: instance.config.maxDate
-      };
-      // blur 시 현재 날짜를 저장하여 잘못된 입력 시 복원에 사용
+      fullValueLengthRef.current = getFullValueLength(dateFormatRef.current);
+      // blur 시 현재 날짜를 저장하여 잘못된 입력 시 복원에 사용하고,
+      // flatpickr가 조용히 반영한 값이 남아 있으면 부모로 올린다 (scheduleBlurSync 주석 참고)
       const onBlurHandler = _e => {
+        // 아래에서 덮어쓰기 전의 값을 넘긴다. 위반 보고 시 previousDate 로 쓰인다
+        const previousDate = instance?._previousDateBeforeInput;
         if (instance && instance.selectedDates.length > 0) {
           instance._previousDateBeforeInput = instance.selectedDates[0];
         }
+        scheduleBlurSync(previousDate);
       };
       input.addEventListener('input', onInputHandler);
       input.addEventListener('blur', onBlurHandler);
@@ -437,6 +538,8 @@ export const DatePicker = /*#__PURE__*/forwardRef((_ref, ref) => {
       const instance = fpInstance;
       const input = instance.input;
       if (!input) return;
+      // 파괴 직전에 이 input 이 포커스를 쥐고 있었는지 기억한다 (restoreFocus 주석 참고)
+      hadFocusBeforeDestroyRef.current = typeof document !== 'undefined' && document.activeElement === input;
       flatpickrInstanceRef.current = null;
       input.removeEventListener('input', onInputHandler);
       const onBlurHandler = instance._onBlurHandler;
@@ -449,7 +552,7 @@ export const DatePicker = /*#__PURE__*/forwardRef((_ref, ref) => {
     ...datePickerOptions,
     // 어드민 환경 — 모바일에서 native picker 로 fallback 되지 않도록 강제 (datePickerOptions 로 override 불가)
     disableMobile: true
-  }), [portal, onChangeDateHandler, onInputHandler, onHourInputHandler, onMinuteInputHandler, datePickerOptions, getPortalContainer]);
+  }), [portal, onChangeDateHandler, onInputHandler, onHourInputHandler, onMinuteInputHandler, datePickerOptions, getPortalContainer, scheduleBlurSync]);
   const iconName = hasTimeOption && datePickerOptions && Object.hasOwn(datePickerOptions, 'noCalendar') ? 'clock' : 'calendar';
   // ──────────────────────────────────────────────
   // 시간 옵션에 따른 currentDate 전처리
@@ -464,6 +567,39 @@ export const DatePicker = /*#__PURE__*/forwardRef((_ref, ref) => {
     if (isTimeOnly) return getTimeOnlyDefault(hasSeconds, isEndDate);
     return getDateTimeDefault(currentDate, hasSeconds, isEndDate);
   }, [currentDate, isEndDate, options.enableSeconds, options.enableTime, options.noCalendar]);
+  // onReady 클로저는 최초 렌더 값에 고정되므로, blur 동기화가 최신 로드값과 비교할 수 있도록 ref에 반영
+  if (loadedDateRef.current !== processedCurrentDate) {
+    loadedDateRef.current = processedCurrentDate;
+    // 부모가 값을 갱신했으면 "이미 통지했다"는 기억은 무효다.
+    // 남겨두면, 사용처가 overlap 통지를 받고 날짜를 되돌린 뒤 사용자가 같은 날짜를 다시 입력할 때
+    // 중복으로 오판해 통지를 건너뛴다 — 콜백이 첫 회만 오고 그 뒤로 안 오는 증상이 된다
+    lastNotifiedDateRef.current = null;
+  }
+  /**
+   * 리렌더로 잃은 포커스를 되돌린다.
+   *
+   * react-flatpickr 는 렌더마다 flatpickr 인스턴스를 destroy/create 하는데, portal 을 안 쓰면
+   * static:true 라 destroy 가 input 을 감싼 .flatpickr-wrapper 를 헐면서 input 노드를 DOM 에서
+   * 옮긴다. 포커스를 쥔 노드를 옮기면 포커스가 풀린다.
+   *
+   * 그래서 사용처가 onDateValidation 을 받고 날짜를 되돌리면, 그 리렌더에서 입력 칸의 포커스가
+   * 빠진다. 사용자는 알럿을 닫고 이어서 타이핑하는데 입력이 아무 데도 들어가지 않아,
+   * 콜백이 "됐다 안 됐다" 하는 것처럼 보인다. (#416)
+   *
+   * 자식(Flatpickr)의 effect 가 먼저 실행되므로 여기서 마지막에 되돌린다.
+   * 포커스가 복원되면 flatpickr 가 캘린더를 여는데, 이는 사용자가 칸을 직접 클릭했을 때와 같은
+   * 상태이므로 그대로 둔다.
+   */
+  // 의도적으로 deps 없음 — 자식 Flatpickr effect 가 인스턴스를 재생성한 뒤에 실행되어야 한다
+  useEffect(() => {
+    if (!hadFocusBeforeDestroyRef.current) return;
+    hadFocusBeforeDestroyRef.current = false;
+    const input = flatpickrInstanceRef.current?.input;
+    if (!input || document.activeElement === input) return;
+    input.focus({
+      preventScroll: true
+    });
+  });
   // ──────────────────────────────────────────────
   // 렌더링
   // ──────────────────────────────────────────────