@ncds/ui-admin 1.8.17 → 1.8.18

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/range-date-picker/RangeDatePicker.d.ts

@@ -13,6 +13,15 @@ type RangeDatePickerProps = {
             period: number;
         };
     };
+    /**
+     * 검증 결과 통지. 시작일·종료일 effect 가 각자 자기 쪽 변경만 검증하므로,
+     * 사용자가 한쪽 날짜를 바꾸면 그 한쪽(`type`)만 통지된다.
+     *
+     * 단 **마운트 시점에 이미 역전된 범위**가 들어오면 두 effect 가 함께 돌아
+     * `type:'start'` 과 `type:'end'` 가 각각 통지된다. 이때 `newDate` 는 서로 반대편 날짜이므로
+     * 양쪽을 모두 반영하면 시작일·종료일이 뒤바뀐다. 한쪽만 처리해야 한다.
+     * (validationOption.setting 을 넘기는 사용처에서는 종전부터 동일하게 동작했다.)
+     */
     onDateValidation?: (params: {
         type: 'start' | 'end';
         errorType: 'reset' | 'period' | 'overlap' | null;

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

@@ -90,17 +90,20 @@ const RangeDatePicker = forwardRef(({ startDateOptions, endDateOptions, validati
         if (!areBothDatesValid(startDateOptions.currentDate, endDateOptions.currentDate)) {
             return;
         }
-        // 종료일이 '오늘'이면 종료측 검증을 건너뛴다: shopby 는 종료일=오늘이 정상 기본값이라
-        // (고도몰=어제) 이 상태를 에러로 잡지 않기 위함. (도입 d1bd8751)
-        const isNotTodayEndDate = !moment(endDateOptions.currentDate).isSame(moment(), 'day');
-        if (!validationOption?.setting || !isNotTodayEndDate) {
-            return;
-        }
+        // overlap(종료일 < 시작일)은 시작일 effect 와 동일하게 setting 유무보다 먼저 검증한다.
+        // 과거에는 아래 setting 가드 뒤에 있어서, setting 을 넘기지 않는 사용처가 종료일을 시작일보다
+        // 앞으로 두어도 onDateValidation 이 호출되지 않았다. (#410)
         const isOverDate = moment(endDateOptions.currentDate).isBefore(startDateOptions.currentDate);
         if (isOverDate) {
             changeSettingDateAndAlert('end');
             return;
         }
+        // 종료일이 '오늘'이면 기간(period) 검증은 건너뛴다: shopby 는 종료일=오늘이 정상 기본값이라
+        // (고도몰=어제) 이 상태를 에러로 잡지 않기 위함. (도입 d1bd8751)
+        const isNotTodayEndDate = !moment(endDateOptions.currentDate).isSame(moment(), 'day');
+        if (!validationOption?.setting || !isNotTodayEndDate) {
+            return;
+        }
         const { unit, period } = validationOption.setting;
         const isValidPeriod = moment(endDateOptions.currentDate).isSameOrBefore(moment(startDateOptions.currentDate).add(period, unit));
         if (isValidPeriod) {

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

@@ -58,3 +58,43 @@ describe('#1 빈/무효 날짜 검증 가드', () => {
         expect(onDateValidation).toHaveBeenCalled();
     });
 });
+describe('#2 validationOption.setting 없이도 overlap 을 검증한다 (#410)', () => {
+    it('종료일이 시작일보다 이전이면 type:end / errorType:overlap 으로 통지한다', () => {
+        const onDateValidation = vi.fn();
+        mount({
+            startDateOptions: { currentDate: '2024-03-10', onChangeDate: () => undefined },
+            endDateOptions: { currentDate: '2024-03-05', onChangeDate: () => undefined },
+            onDateValidation,
+        });
+        expect(onDateValidation).toHaveBeenCalledWith({
+            type: 'end',
+            errorType: 'overlap',
+            newDate: '2024-03-10',
+            currentDate: '2024-03-05',
+        });
+    });
+    it('시작일이 종료일보다 이후이면 type:start / errorType:overlap 으로 통지한다', () => {
+        const onDateValidation = vi.fn();
+        mount({
+            startDateOptions: { currentDate: '2024-03-10', onChangeDate: () => undefined },
+            endDateOptions: { currentDate: '2024-03-05', onChangeDate: () => undefined },
+            onDateValidation,
+        });
+        expect(onDateValidation).toHaveBeenCalledWith({
+            type: 'start',
+            errorType: 'overlap',
+            newDate: '2024-03-05',
+            currentDate: '2024-03-10',
+        });
+    });
+    it('정상 범위(시작일 <= 종료일)면 setting 없이 overlap 을 통지하지 않는다', () => {
+        const onDateValidation = vi.fn();
+        mount({
+            startDateOptions: { currentDate: '2024-03-01', onChangeDate: () => undefined },
+            endDateOptions: { currentDate: '2024-03-05', onChangeDate: () => undefined },
+            onDateValidation,
+        });
+        const overlapCalls = onDateValidation.mock.calls.filter(([arg]) => arg?.errorType === 'overlap');
+        expect(overlapCalls).toHaveLength(0);
+    });
+});

package/dist/temp/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';
@@ -40,3 +40,192 @@ describe('#6 periodItems 에 없는 periodKey 방어', () => {
         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 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(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 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(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 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(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/temp/vitest.config.js

@@ -1,4 +1,9 @@
+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: [
@@ -7,5 +12,24 @@ export default defineConfig({
             'assets/scripts/**/__tests__/**/*.test.ts',
         ],
         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/types/src/components/forms-and-input/range-date-picker/RangeDatePicker.d.ts

@@ -13,6 +13,15 @@ type RangeDatePickerProps = {
             period: number;
         };
     };
+    /**
+     * 검증 결과 통지. 시작일·종료일 effect 가 각자 자기 쪽 변경만 검증하므로,
+     * 사용자가 한쪽 날짜를 바꾸면 그 한쪽(`type`)만 통지된다.
+     *
+     * 단 **마운트 시점에 이미 역전된 범위**가 들어오면 두 effect 가 함께 돌아
+     * `type:'start'` 과 `type:'end'` 가 각각 통지된다. 이때 `newDate` 는 서로 반대편 날짜이므로
+     * 양쪽을 모두 반영하면 시작일·종료일이 뒤바뀐다. 한쪽만 처리해야 한다.
+     * (validationOption.setting 을 넘기는 사용처에서는 종전부터 동일하게 동작했다.)
+     */
     onDateValidation?: (params: {
         type: 'start' | 'end';
         errorType: 'reset' | 'period' | 'overlap' | null;