@ncds/ui-admin 1.8.17 → 1.8.18

package/dist/esm/src/components/forms-and-input/range-date-picker-with-buttons/__tests__/RangeDatePickerWithButtons.test.js

@@ -1,5 +1,5 @@
 // @vitest-environment jsdom
-import { createElement } from 'react';
+import { createElement, useState } from 'react';
 import { createRoot } from 'react-dom/client';
 import { act } from 'react-dom/test-utils';
 import { afterEach, describe, expect, it, vi } from 'vitest';
@@ -51,4 +51,253 @@ describe('#6 periodItems 에 없는 periodKey 방어', () => {
     // 유효한 키(TODAY='오늘')는 렌더되고, 정의에 없는 키는 건너뛴다(크래시 없음)
     expect(container.textContent).toContain('오늘');
   });
+});
+describe('#9 allowInput 타이핑 → onDateValidation (#410)', () => {
+  const START_DATE = '2026-03-10';
+  const END_DATE = '2026-03-20';
+  /** 시작일보다 이전 — 종료일에 넣으면 overlap */
+  const TYPED_END_DATE = '2026-03-01';
+  /** 실제 사용처처럼 부모가 state 를 들고 controlled 로 쓰는 래퍼.
+   *  bump() 로 날짜와 무관한 리렌더를 임의 시점에 끼워 넣을 수 있다. */
+  function mountHarness(onDateValidation) {
+    let bump;
+    const Harness = () => {
+      const [start, setStart] = useState(START_DATE);
+      const [end, setEnd] = useState(END_DATE);
+      const [, setTick] = useState(0);
+      const [buttonId, setButtonId] = useState('NONE');
+      bump = () => setTick(tick => tick + 1);
+      return /*#__PURE__*/createElement(RangeDatePickerWithButtons, {
+        currentButtonId: buttonId,
+        setCurrentButtonId: setButtonId,
+        periodKeys: ['ENTIRE', 'TODAY'],
+        startDateOptions: {
+          currentDate: start,
+          onChangeDate: setStart,
+          datePickerOptions: {
+            allowInput: true
+          }
+        },
+        endDateOptions: {
+          currentDate: end,
+          onChangeDate: setEnd,
+          datePickerOptions: {
+            allowInput: true
+          }
+        },
+        onDateValidation
+      });
+    };
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    const root = createRoot(container);
+    act(() => {
+      root.render(/*#__PURE__*/createElement(Harness));
+    });
+    mounted.push({
+      root,
+      container
+    });
+    const inputs = Array.from(container.querySelectorAll('input.flatpickr-input'));
+    return {
+      endInput: inputs[1],
+      bump: () => bump?.()
+    };
+  }
+  const typeChar = (input, char) => {
+    act(() => {
+      input.value = `${input.value}${char}`;
+      input.dispatchEvent(new Event('input', {
+        bubbles: true
+      }));
+    });
+  };
+  it('종료일에 시작일 이전 날짜를 타이핑하면 overlap 을 통지한다', () => {
+    const onDateValidation = vi.fn();
+    const {
+      endInput
+    } = mountHarness(onDateValidation);
+    onDateValidation.mockClear();
+    endInput.value = '';
+    for (const char of TYPED_END_DATE) {
+      typeChar(endInput, char);
+    }
+    expect(onDateValidation).toHaveBeenCalledWith({
+      type: 'end',
+      errorType: 'overlap',
+      newDate: START_DATE,
+      currentDate: TYPED_END_DATE
+    });
+  });
+  it('blur 없이 통지하므로, 통지 이후 부모가 리렌더돼도 결과가 뒤집히지 않는다', () => {
+    const onDateValidation = vi.fn();
+    const {
+      endInput,
+      bump
+    } = mountHarness(onDateValidation);
+    onDateValidation.mockClear();
+    endInput.value = '';
+    for (const char of TYPED_END_DATE) {
+      typeChar(endInput, char);
+    }
+    onDateValidation.mockClear();
+    // 날짜와 무관한 리렌더가 뒤따라도 통지된 값이 유지된다
+    act(() => {
+      bump();
+    });
+    expect(endInput.value).toBe(TYPED_END_DATE);
+  });
+  /**
+   * 알려진 한계: 날짜를 다 치기 전에 리렌더가 끼면 react-flatpickr 가 input 을 부모 값으로 덮는다.
+   * (static:true 라 wrapper 를 헐고 다시 만들면서 input DOM 이 이동해 포커스까지 빠진다.)
+   * 통지 자체는 blur 를 안 기다리므로 위 케이스와 무관하지만, 이 구간은 여전히 취약하다.
+   */
+  it('입력이 완성되기 전 리렌더가 끼면 입력값이 부모 값으로 되돌아간다 (알려진 한계)', () => {
+    const onDateValidation = vi.fn();
+    const {
+      endInput,
+      bump
+    } = mountHarness(onDateValidation);
+    endInput.value = '';
+    for (const char of TYPED_END_DATE.slice(0, -1)) {
+      typeChar(endInput, char);
+    }
+    act(() => {
+      bump();
+    });
+    expect(endInput.value).toBe(END_DATE);
+  });
+});
+describe('#10 같은 날짜를 다시 입력해도 통지된다 (#410 재보고)', () => {
+  const START_DATE = '2026-08-10';
+  const END_DATE = '2026-08-20';
+  /** 시작일 이전 — overlap */
+  const TYPED_END_DATE = '2026-08-06';
+  const typeChars = (input, text) => {
+    input.value = '';
+    for (const char of text) {
+      act(() => {
+        input.value = `${input.value}${char}`;
+        input.dispatchEvent(new Event('input', {
+          bubbles: true
+        }));
+      });
+    }
+  };
+  it('overlap 통지를 받고 종료일을 되돌린 뒤 같은 날짜를 다시 쳐도 매번 통지한다', () => {
+    const onDateValidation = vi.fn();
+    // 실제 사용처 패턴: overlap 을 받으면 알럿 대신 종료일을 원래대로 되돌린다
+    const Harness = () => {
+      const [start, setStart] = useState(START_DATE);
+      const [end, setEnd] = useState(END_DATE);
+      const [buttonId, setButtonId] = useState('NONE');
+      return /*#__PURE__*/createElement(RangeDatePickerWithButtons, {
+        currentButtonId: buttonId,
+        setCurrentButtonId: setButtonId,
+        periodKeys: ['ENTIRE', 'TODAY'],
+        startDateOptions: {
+          currentDate: start,
+          onChangeDate: setStart,
+          datePickerOptions: {
+            allowInput: true
+          }
+        },
+        endDateOptions: {
+          currentDate: end,
+          onChangeDate: setEnd,
+          datePickerOptions: {
+            allowInput: true
+          }
+        },
+        onDateValidation: params => {
+          onDateValidation(params);
+          if (params.type === 'end' && params.errorType === 'overlap') setEnd(END_DATE);
+        }
+      });
+    };
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    const root = createRoot(container);
+    act(() => {
+      root.render(/*#__PURE__*/createElement(Harness));
+    });
+    mounted.push({
+      root,
+      container
+    });
+    const endInput = Array.from(container.querySelectorAll('input.flatpickr-input'))[1];
+    onDateValidation.mockClear();
+    // 종전에는 lastNotifiedDate 가 부모 갱신 후에도 남아 있어 2회차부터 통지가 끊겼다
+    const ATTEMPT_COUNT = 3;
+    const firedPerAttempt = [];
+    for (let attempt = 0; attempt < ATTEMPT_COUNT; attempt++) {
+      const before = onDateValidation.mock.calls.length;
+      typeChars(endInput, TYPED_END_DATE);
+      firedPerAttempt.push(onDateValidation.mock.calls.length - before);
+    }
+    expect(firedPerAttempt).toEqual([1, 1, 1]);
+  });
+});
+describe('#11 통지 후 사용처가 날짜를 되돌려도 입력 칸의 포커스가 유지된다 (#416)', () => {
+  const START_DATE = '2026-08-10';
+  const END_DATE = '2026-08-20';
+  /** 시작일 이전 — overlap */
+  const TYPED_END_DATE = '2026-08-06';
+  it('overlap 통지 → 되돌리기 후에도 input 이 포커스를 잃지 않는다', () => {
+    const Harness = () => {
+      const [start, setStart] = useState(START_DATE);
+      const [end, setEnd] = useState(END_DATE);
+      const [buttonId, setButtonId] = useState('NONE');
+      return /*#__PURE__*/createElement(RangeDatePickerWithButtons, {
+        currentButtonId: buttonId,
+        setCurrentButtonId: setButtonId,
+        periodKeys: ['ENTIRE', 'TODAY'],
+        startDateOptions: {
+          currentDate: start,
+          onChangeDate: setStart,
+          datePickerOptions: {
+            allowInput: true
+          }
+        },
+        endDateOptions: {
+          currentDate: end,
+          onChangeDate: setEnd,
+          datePickerOptions: {
+            allowInput: true
+          }
+        },
+        onDateValidation: params => {
+          // 알럿 후 날짜를 되돌리는 사용처 패턴
+          if (params.type === 'end' && params.errorType === 'overlap') setEnd(END_DATE);
+        }
+      });
+    };
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    const root = createRoot(container);
+    act(() => {
+      root.render(/*#__PURE__*/createElement(Harness));
+    });
+    mounted.push({
+      root,
+      container
+    });
+    const endInput = Array.from(container.querySelectorAll('input.flatpickr-input'))[1];
+    // 사용자가 칸을 클릭해 포커스를 쥔 상태로 입력한다
+    endInput.focus();
+    expect(document.activeElement).toBe(endInput);
+    endInput.value = '';
+    for (const char of TYPED_END_DATE) {
+      act(() => {
+        endInput.value = `${endInput.value}${char}`;
+        endInput.dispatchEvent(new Event('input', {
+          bubbles: true
+        }));
+      });
+    }
+    // 되돌리기 리렌더에서 flatpickr 가 wrapper 를 재생성하며 input 노드를 옮겨 포커스가 빠졌다.
+    // 사용자는 알럿을 닫고 이어서 타이핑하는데 입력이 들어가지 않아 콜백이 끊긴 것처럼 보였다.
+    expect(endInput.value).toBe(END_DATE);
+    expect(document.activeElement).toBe(endInput);
+  });
 });

package/dist/esm/vitest.config.js

@@ -1,7 +1,28 @@
+import path from 'node:path';
 import { defineConfig } from 'vitest/config';
+// lcov 의 SF 경로를 레포 루트 기준으로 기록한다. sonar-scanner 는 레포 루트를 단일
+// projectBaseDir 로 잡으므로, 패키지 루트 기준 상대경로(SF:src/foo.ts)로 두면 경로가
+// 해석되지 않아 커버리지가 통째로 무시된다.
+const REPO_ROOT = path.resolve(__dirname, '../..');
 export default defineConfig({
   test: {
     include: ['scripts/**/__tests__/**/*.test.ts', 'src/**/__tests__/**/*.test.ts', 'assets/scripts/**/__tests__/**/*.test.ts'],
-    environment: 'node'
+    environment: 'node',
+    coverage: {
+      provider: 'v8',
+      // 테스트가 존재하는 3개 루트를 분모로 잡는다 (test.include 와 동일 범위).
+      include: ['src/**/*.{ts,tsx}', 'scripts/**/*.ts', 'assets/scripts/**/*.ts'],
+      exclude: ['**/__tests__/**', '**/*.d.ts',
+      // ui-admin 의 index.ts 81개는 전부 `export * from ...` barrel 이라 측정 의미가 없다.
+      // (step-guide 의 src/index.ts 는 824줄 본체 구현이므로 그쪽에서는 제외하지 않는다.)
+      '**/index.ts',
+      // MCP 가 읽는 컴포넌트 메타데이터 선언 45개 — 실행 분기 없는 순수 데이터.
+      '**/*.meta.ts', 'src/types/**', 'src/constant/**'],
+      // 'text' 미포함 — 미커버 파일이 수백 개라 파일별 상세 출력이 CI 로그를 덮는다.
+      // 'lcov' 대신 'lcovonly' — 'lcov' 는 HTML 리포트까지 생성한다.
+      reporter: ['text-summary', ['lcovonly', {
+        projectRoot: REPO_ROOT
+      }]]
+    }
   }
 });

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

@@ -49,6 +49,24 @@ 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';
@@ -196,7 +214,10 @@ const cleanupTimeInputHandlers = (instance, input, isPortal, onHourInput, onMinu
 export const DatePicker = forwardRef(({ shouldFocus = true, currentDate, size = 'xs', onChangeDate, datePickerOptions, isEndDate = false, onValidationError, className, portal = false, ...attrs }, 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');
@@ -205,6 +226,12 @@ export const DatePicker = forwardRef(({ shouldFocus = true, currentDate, size =
     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')
@@ -224,11 +251,15 @@ export const DatePicker = forwardRef(({ shouldFocus = true, currentDate, size =
         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;
+            }
         };
     }, []);
     // ──────────────────────────────────────────────
@@ -271,6 +302,72 @@ export const DatePicker = forwardRef(({ shouldFocus = true, currentDate, size =
         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;
@@ -281,27 +378,42 @@ export const DatePicker = forwardRef(({ shouldFocus = true, currentDate, size =
         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,
-            });
+        // 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;
@@ -312,7 +424,7 @@ export const DatePicker = forwardRef(({ shouldFocus = true, currentDate, size =
         if (!input?.trim()) {
             target.value = '';
             instance.setDate('', false);
-            onChangeDateRef.current('');
+            commitDate('');
             return;
         }
         if (!/[0-9]/.test(input)) {
@@ -321,22 +433,21 @@ export const DatePicker = forwardRef(({ shouldFocus = true, currentDate, size =
         }
         const formattedInput = formatDateInput(input);
         if (formattedInput !== input) {
+            // 여기서 멈추지 않는다. 8자리 숫자를 다 치거나 붙여넣으면 이 시점에 이미 완성된
+            // 날짜이고, 우리가 다시 쓴 값에 대해 브라우저는 input 이벤트를 더 주지 않는다.
             target.value = formattedInput;
-            return;
         }
-        if (!formattedInput || formattedInput.length < 10)
+        // 완성 전에는 검증하지 않는다. 중간 상태를 완성으로 오판하면 아래에서 입력이 되돌아간다
+        if (formattedInput.length < fullValueLengthRef.current)
             return;
-        const parsedDate = moment(formattedInput);
-        if (!parsedDate.isValid()) {
+        // 포맷을 넘겨 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;
@@ -398,15 +509,16 @@ export const DatePicker = forwardRef(({ shouldFocus = true, currentDate, size =
                 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);
@@ -432,6 +544,8 @@ export const DatePicker = forwardRef(({ shouldFocus = true, currentDate, size =
             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;
@@ -452,6 +566,7 @@ export const DatePicker = forwardRef(({ shouldFocus = true, currentDate, size =
         onMinuteInputHandler,
         datePickerOptions,
         getPortalContainer,
+        scheduleBlurSync,
     ]);
     const iconName = hasTimeOption && datePickerOptions && Object.hasOwn(datePickerOptions, 'noCalendar') ? 'clock' : 'calendar';
     // ──────────────────────────────────────────────
@@ -470,6 +585,39 @@ export const DatePicker = forwardRef(({ shouldFocus = true, currentDate, size =
             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 });
+    });
     // ──────────────────────────────────────────────
     // 렌더링
     // ──────────────────────────────────────────────