@ncds/ui-admin 1.8.16 → 1.8.18

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 });
+    });
     // ──────────────────────────────────────────────
     // 렌더링
     // ──────────────────────────────────────────────

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

@@ -107,3 +107,326 @@ describe('#3 onValidationError.previousDate', () => {
         expect(arg.previousDate?.getTime()).not.toBe(arg.date.getTime());
     });
 });
+describe('#5 blur 동기화 — flatpickr가 통지하지 않은 값 보정 (#410)', () => {
+    const getInstance = (container) => {
+        const input = container.querySelector('input');
+        expect(input._flatpickr).toBeTruthy();
+        return { input, instance: input._flatpickr };
+    };
+    /** blur 동기화는 한 틱 뒤에 실행되므로 매크로태스크를 한 번 흘려보낸다 */
+    const flushBlurSync = async () => {
+        await act(async () => {
+            await new Promise((resolve) => setTimeout(resolve, 0));
+        });
+    };
+    it('onChange 없이 값만 반영된 채 blur 되면 onChangeDate 로 통지한다', async () => {
+        const onChangeDate = vi.fn();
+        const container = mount({
+            currentDate: '2024-03-01',
+            onChangeDate,
+            datePickerOptions: { allowInput: true },
+        });
+        const { input, instance } = getInstance(container);
+        // flatpickr documentClick 이 하는 것과 동일하게, onChange 를 발화시키지 않고 값만 반영한다
+        act(() => {
+            instance.setDate('2024-03-20', false);
+        });
+        onChangeDate.mockClear();
+        act(() => {
+            input.dispatchEvent(new Event('blur'));
+        });
+        await flushBlurSync();
+        expect(onChangeDate).toHaveBeenCalledWith('2024-03-20');
+    });
+    it('flatpickr가 이미 onChange 로 통지했으면 blur 가 중복 통지하지 않는다', async () => {
+        const onChangeDate = vi.fn();
+        const container = mount({
+            currentDate: '2024-03-01',
+            onChangeDate,
+            datePickerOptions: { allowInput: true },
+        });
+        const { input, instance } = getInstance(container);
+        act(() => {
+            instance.setDate('2024-03-20', true);
+        });
+        expect(onChangeDate).toHaveBeenCalledTimes(1);
+        act(() => {
+            input.dispatchEvent(new Event('blur'));
+        });
+        await flushBlurSync();
+        expect(onChangeDate).toHaveBeenCalledTimes(1);
+    });
+    it('min/max 위반 값은 blur 로도 통지하지 않고 onValidationError 로 보고한다', async () => {
+        const onChangeDate = vi.fn();
+        const onValidationError = vi.fn();
+        const container = mount({
+            currentDate: '2024-03-15',
+            onChangeDate,
+            onValidationError,
+            datePickerOptions: { minDate: '2024-03-10', maxDate: '2024-03-25', allowInput: true },
+        });
+        const { input, instance } = getInstance(container);
+        // 범위 밖 날짜가 onChange 없이 값만 반영된 상태 (마우스로 캘린더 밖 클릭 시 flatpickr 동작)
+        act(() => {
+            instance.setDate('2024-04-30', false);
+        });
+        onChangeDate.mockClear();
+        onValidationError.mockClear();
+        act(() => {
+            input.dispatchEvent(new Event('blur'));
+        });
+        await flushBlurSync();
+        expect(onChangeDate).not.toHaveBeenCalled();
+        expect(onValidationError).toHaveBeenCalledTimes(1);
+        expect(onValidationError.mock.calls[0][0].violations).toContain('maxDate');
+    });
+    it('enableTime 모드에서 값 변경 없이 blur 해도 통지하지 않는다', async () => {
+        const onChangeDate = vi.fn();
+        const container = mount({
+            currentDate: '2024-03-20',
+            onChangeDate,
+            datePickerOptions: { enableTime: true, dateFormat: 'Y-m-d H:i', allowInput: true },
+        });
+        const { input } = getInstance(container);
+        onChangeDate.mockClear();
+        act(() => {
+            input.dispatchEvent(new Event('blur'));
+        });
+        await flushBlurSync();
+        expect(onChangeDate).not.toHaveBeenCalled();
+    });
+    it('noCalendar(시간 전용) 모드에서 값 변경 없이 blur 해도 통지하지 않는다', async () => {
+        const onChangeDate = vi.fn();
+        const container = mount({
+            currentDate: '',
+            onChangeDate,
+            datePickerOptions: { enableTime: true, noCalendar: true, dateFormat: 'H:i', allowInput: true },
+        });
+        const { input } = getInstance(container);
+        onChangeDate.mockClear();
+        act(() => {
+            input.dispatchEvent(new Event('blur'));
+        });
+        await flushBlurSync();
+        expect(onChangeDate).not.toHaveBeenCalled();
+    });
+    it('noCalendar(시간 전용) 모드에서 통지 없이 시간만 바뀐 채 blur 되면 통지한다', async () => {
+        const onChangeDate = vi.fn();
+        const container = mount({
+            currentDate: '',
+            onChangeDate,
+            datePickerOptions: { enableTime: true, noCalendar: true, dateFormat: 'H:i', allowInput: true },
+        });
+        const { input, instance } = getInstance(container);
+        act(() => {
+            instance.setDate('14:30', false);
+        });
+        onChangeDate.mockClear();
+        act(() => {
+            input.dispatchEvent(new Event('blur'));
+        });
+        await flushBlurSync();
+        expect(onChangeDate).toHaveBeenCalledWith('14:30');
+    });
+    it('portal 모드에서도 통지 없이 값만 반영된 채 blur 되면 통지한다', async () => {
+        const onChangeDate = vi.fn();
+        const container = mount({
+            currentDate: '2024-03-01',
+            onChangeDate,
+            portal: true,
+            datePickerOptions: { allowInput: true },
+        });
+        const { input, instance } = getInstance(container);
+        act(() => {
+            instance.setDate('2024-03-20', false);
+        });
+        onChangeDate.mockClear();
+        act(() => {
+            input.dispatchEvent(new Event('blur'));
+        });
+        await flushBlurSync();
+        expect(onChangeDate).toHaveBeenCalledWith('2024-03-20');
+    });
+    it('값이 바뀌지 않았으면 blur 만으로는 통지하지 않는다', async () => {
+        const onChangeDate = vi.fn();
+        const container = mount({
+            currentDate: '2024-03-01',
+            onChangeDate,
+            datePickerOptions: { allowInput: true },
+        });
+        const { input } = getInstance(container);
+        onChangeDate.mockClear();
+        act(() => {
+            input.dispatchEvent(new Event('blur'));
+        });
+        await flushBlurSync();
+        expect(onChangeDate).not.toHaveBeenCalled();
+    });
+});
+describe('#7 타이핑 즉시 통지 — blur 를 기다리지 않는다 (#410)', () => {
+    const getInput = (container) => container.querySelector('input.flatpickr-input');
+    /** 사용자가 한 글자씩 타이핑하는 것과 동일하게 input 이벤트를 발생시킨다 */
+    const typeInto = (input, text) => {
+        input.value = '';
+        for (const char of text) {
+            act(() => {
+                input.value = `${input.value}${char}`;
+                input.dispatchEvent(new Event('input', { bubbles: true }));
+            });
+        }
+    };
+    const flushBlurSync = async () => {
+        await act(async () => {
+            await new Promise((resolve) => setTimeout(resolve, 0));
+        });
+    };
+    it('완성된 유효 날짜를 타이핑하면 blur 전에 통지한다', () => {
+        const onChangeDate = vi.fn();
+        const container = mount({
+            currentDate: '2024-03-01',
+            onChangeDate,
+            datePickerOptions: { allowInput: true },
+        });
+        typeInto(getInput(container), '2024-03-20');
+        expect(onChangeDate).toHaveBeenCalledWith('2024-03-20');
+    });
+    it('구분자 없이 8자리 숫자만 타이핑해도 통지한다', () => {
+        const onChangeDate = vi.fn();
+        const container = mount({
+            currentDate: '2024-03-01',
+            onChangeDate,
+            datePickerOptions: { allowInput: true },
+        });
+        // 8자리를 다 치는 순간 핸들러가 값을 '2024-03-20' 으로 다시 쓴다.
+        // 그 뒤로는 브라우저가 input 이벤트를 더 주지 않으므로 이 시점에 통지해야 한다.
+        typeInto(getInput(container), '20240320');
+        expect(onChangeDate).toHaveBeenCalledWith('2024-03-20');
+    });
+    it('아직 완성되지 않은 입력은 통지하지 않는다', () => {
+        const onChangeDate = vi.fn();
+        const container = mount({
+            currentDate: '2024-03-01',
+            onChangeDate,
+            datePickerOptions: { allowInput: true },
+        });
+        typeInto(getInput(container), '2024-03-');
+        expect(onChangeDate).not.toHaveBeenCalled();
+    });
+    it('타이핑으로 이미 통지했으면 blur 가 중복 통지하지 않는다', async () => {
+        const onChangeDate = vi.fn();
+        const container = mount({
+            currentDate: '2024-03-01',
+            onChangeDate,
+            datePickerOptions: { allowInput: true },
+        });
+        const input = getInput(container);
+        typeInto(input, '2024-03-20');
+        expect(onChangeDate).toHaveBeenCalledTimes(1);
+        act(() => {
+            input.dispatchEvent(new Event('blur'));
+        });
+        await flushBlurSync();
+        expect(onChangeDate).toHaveBeenCalledTimes(1);
+    });
+    it('min/max 범위 밖 날짜는 타이핑 중에 통지하지 않는다 (blur 시점에 한 번만 보고)', () => {
+        const onChangeDate = vi.fn();
+        const onValidationError = vi.fn();
+        const container = mount({
+            currentDate: '2024-03-15',
+            onChangeDate,
+            onValidationError,
+            datePickerOptions: { minDate: '2024-03-10', maxDate: '2024-03-25', allowInput: true },
+        });
+        typeInto(getInput(container), '2024-04-30');
+        expect(onChangeDate).not.toHaveBeenCalled();
+        expect(onValidationError).not.toHaveBeenCalled();
+    });
+    it('같은 값은 경로가 달라도 두 번 통지하지 않는다', () => {
+        const onChangeDate = vi.fn();
+        const container = mount({
+            currentDate: '2024-03-01',
+            onChangeDate,
+            datePickerOptions: { allowInput: true },
+        });
+        const input = getInput(container);
+        // 타이핑으로 통지한 뒤, 캘린더가 같은 날짜로 onChange 를 다시 발화시키는 상황
+        typeInto(input, '2024-03-20');
+        act(() => {
+            input._flatpickr.setDate('2024-03-20', true);
+        });
+        expect(onChangeDate).toHaveBeenCalledTimes(1);
+    });
+    it('enableTime 모드에서 날짜만 입력한 상태는 타이핑 중에 통지하지 않는다', () => {
+        const onChangeDate = vi.fn();
+        const container = mount({
+            currentDate: '2024-03-01 00:00',
+            onChangeDate,
+            datePickerOptions: { enableTime: true, dateFormat: 'Y-m-d H:i', allowInput: true },
+        });
+        // '2024-03-20' 은 최종 표기('2024-03-20 00:00')와 다르다.
+        // 여기서 통지하면 setDate 가 input 을 다시 써서 타이핑 중 커서가 튄다.
+        typeInto(getInput(container), '2024-03-20');
+        expect(onChangeDate).not.toHaveBeenCalled();
+    });
+});
+describe('#8 완성 판정·파싱을 dateFormat 기준으로 한다', () => {
+    const getInput = (container) => container.querySelector('input.flatpickr-input');
+    const typeInto = (input, text) => {
+        input.value = '';
+        for (const char of text) {
+            act(() => {
+                input.value = `${input.value}${char}`;
+                input.dispatchEvent(new Event('input', { bubbles: true }));
+            });
+        }
+    };
+    it('enableTime 에서 한 글자씩 쳐도 입력이 유지되고 통지된다', () => {
+        const onChangeDate = vi.fn();
+        const container = mount({
+            currentDate: '2026-03-20 23:59',
+            onChangeDate,
+            datePickerOptions: { allowInput: true, enableTime: true, dateFormat: 'Y-m-d H:i' },
+        });
+        const input = getInput(container);
+        // 완성 길이를 10 으로 고정하면 '2026-03-01 0' 을 완성으로 오판해
+        // moment 검증에 걸리고, 입력이 이전 값('2026-03-20 23:59')으로 되돌아갔다
+        typeInto(input, '2026-03-01 00:00');
+        expect(input.value).toBe('2026-03-01 00:00');
+        expect(onChangeDate).toHaveBeenCalledWith('2026-03-01 00:00');
+    });
+    it('enableTime 에서 시간을 아직 안 친 중간 상태는 통지하지 않는다', () => {
+        const onChangeDate = vi.fn();
+        const container = mount({
+            currentDate: '2026-03-20 23:59',
+            onChangeDate,
+            datePickerOptions: { allowInput: true, enableTime: true, dateFormat: 'Y-m-d H:i' },
+        });
+        typeInto(getInput(container), '2026-03-01 00');
+        expect(onChangeDate).not.toHaveBeenCalled();
+    });
+    it('시간 전용(noCalendar) 모드에서 타이핑한 값이 되돌려지지 않는다', () => {
+        const onChangeDate = vi.fn();
+        const container = mount({
+            currentDate: '23:59',
+            onChangeDate,
+            datePickerOptions: { allowInput: true, enableTime: true, noCalendar: true, dateFormat: 'H:i' },
+        });
+        const input = getInput(container);
+        // 포맷 없이 moment('14:30') 으로 파싱하면 invalid 라 이전 값으로 복원됐다
+        typeInto(input, '14:30');
+        expect(input.value).toBe('14:30');
+        expect(onChangeDate).toHaveBeenCalledWith('14:30');
+    });
+    it('완성 길이에 도달했지만 실재하지 않는 날짜는 이전 값으로 복원한다', () => {
+        const onChangeDate = vi.fn();
+        const container = mount({
+            currentDate: '2026-03-20',
+            onChangeDate,
+            datePickerOptions: { allowInput: true },
+        });
+        const input = getInput(container);
+        typeInto(input, '2026-13-45');
+        expect(input.value).not.toBe('2026-13-45');
+        expect(onChangeDate).not.toHaveBeenCalledWith('2026-13-45');
+    });
+});

package/dist/temp/src/components/forms-and-input/file-input/FileInput.d.ts

@@ -57,5 +57,13 @@ export interface FileInputProps extends Omit<InputBaseProps, 'clearText' | 'onCl
      * Hint text to display
      */
     hintText?: string;
+    /**
+     * Whether to render the built-in file tag list
+     *
+     * Set to `false` when the file list is rendered outside the component —
+     * the selected files still arrive through `onChange` / `onFileSelect`, and
+     * file count/duplicate validation keeps working.
+     */
+    showFileTags?: boolean;
 }
 export declare const FileInput: import("react").ForwardRefExoticComponent<FileInputProps & import("react").RefAttributes<HTMLInputElement>>;