@idbrnd/design-system 4.2.2 → 4.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @idbrnd/design-system
 
-![Version](https://img.shields.io/static/v1?label=version&message=4.2.2&color=blue&style=flat-square) <!-- x-release-please-version -->
+![Version](https://img.shields.io/static/v1?label=version&message=4.3.0&color=blue&style=flat-square) <!-- x-release-please-version -->
 ![React](https://img.shields.io/badge/React-18.3.1-61DAFB?style=flat-square&logo=react&logoColor=white)
 ![Vite](https://img.shields.io/badge/Vite-7.3.0-646CFF?style=flat-square&logo=vite&logoColor=white)
 ![TypeScript](https://img.shields.io/badge/TypeScript-5.9.3-3178C6?style=flat-square&logo=typescript&logoColor=white)
@@ -1179,6 +1179,26 @@ function RangeExample() {
 <DatePicker variant="period" hasTime timeVariant="hh-mm" value={range} onChange={setRange} />
 ```
 
+**범위 유효성 검증 (minDurationMinutes / maxRangeDays)**
+
+`period`/`range`에서 시작~종료 사이 최소 간격(분) 또는 최대 기간(일)을 제한할 수 있습니다.
+위반 시 적용(Apply) 버튼이 비활성화되며, `hasTime` 여부와 무관하게 종료가 시작보다 빠른 경우도
+함께 걸러집니다. 각 위반 종류별 토스트 메시지는 opt-in이라 미지정 시 토스트 없이 적용만 막힙니다.
+
+```tsx
+<DatePicker
+  variant="range"
+  hasTime
+  value={range}
+  onChange={setRange}
+  minDurationMinutes={30} // 시작~종료 최소 30분. hasTime일 때만 검증됨
+  maxRangeDays={7} // 시작~종료 최대 7일. hasTime과 무관하게 검증됨
+  timeOrderToastText="종료 시간은 시작 시간 이후여야 해요"
+  minDurationToastText="최소 30분 이상 선택해 주세요"
+  maxRangeToastText="최대 7일까지 선택할 수 있어요"
+/>
+```
+
 **특정 날짜 비활성화**
 
 ```tsx
@@ -1253,6 +1273,11 @@ function isDateDisabled(date: Date) {
 | `monthYearActionArea`| `boolean`                                                      | `true`                | 헤더의 연/월 라벨 클릭 시 빠른 선택 드롭다운 노출 여부                          |
 | `startLabel`         | `string`                                                       | `"시작"`              | `hasTime`일 때 시작 시간 행의 라벨                                               |
 | `endLabel`           | `string`                                                       | `"종료"`              | `hasTime && (period\|range)`일 때 종료 시간 행의 라벨                           |
+| `minDurationMinutes` | `number`                                                       | —                     | `period`/`range`에서 시작~종료 최소 간격(분). `hasTime`일 때만 검증됨. 미지정 시 검증 안 함 |
+| `maxRangeDays`       | `number`                                                       | —                     | `period`/`range`에서 시작~종료 최대 기간(일). `hasTime`과 무관하게 검증됨. 미지정 시 검증 안 함 |
+| `timeOrderToastText` | `string`                                                       | —                     | 종료가 시작보다 빠를 때 노출되는 토스트 메시지. 미지정 시 토스트 없이 적용만 막힘 |
+| `minDurationToastText` | `string`                                                     | —                     | `minDurationMinutes` 위반 시 노출되는 토스트 메시지. 미지정 시 토스트 없이 적용만 막힘 |
+| `maxRangeToastText`  | `string`                                                       | —                     | `maxRangeDays` 위반 시 노출되는 토스트 메시지. 미지정 시 토스트 없이 적용만 막힘  |
 | `weekdayLabels`      | `readonly string[]`                                            | `["월",…,"일"]`       | 요일 라벨. 월요일부터 순서대로 7개 전달                                          |
 | `amLabel` / `pmLabel`| `string`                                                       | `"오전"` / `"오후"`   | 시간 선택 휠의 오전/오후 라벨                                                    |
 | `formatMonthYear`    | `(year: number, month: number) => string`                      | —                     | "2026년 8월" 헤더 포맷 override. `month`는 1~12로 전달                          |
@@ -1281,6 +1306,8 @@ function isDateDisabled(date: Date) {
 - 팝오버는 `document.body`에 포탈로 렌더링되며, 뷰포트 하단 공간이 부족하면 트리거 위쪽으로 자동 전환(flip)됩니다.
 - `actionSubContent`/`actionMainContent`를 함수로 전달하면 인자로 받는 `onClick`이 기본 동작(오늘로 이동 / 적용)을 그대로 실행하므로, 라벨이나 마크업만 바꾼 커스텀 요소에도 기존 동작을 재사용할 수 있습니다. `ReactNode`를 직접 전달하면 완전히 다른 요소로 교체되며 동작은 직접 구현해야 합니다.
 - `hasTime`일 때 시간 필드는 [TimePicker](#timepicker)를 그대로 임베드한 것으로, `actionArea`/`actionSub`/`actionMainType`이 동일하게 전달됩니다. 예를 들어 `actionArea={false}`면 날짜뿐 아니라 시간도 휠에서 값을 고르는 즉시 커밋됩니다.
+- `period`/`range`에서 당일(시작일=종료일) 선택은 `hasTime`이 `true`일 때만 허용됩니다. `hasTime`이 `false`면 같은 날짜를 다시 클릭해도 새 선택으로 재시작될 뿐 당일 range는 만들어지지 않습니다.
+- `minDurationMinutes`/`maxRangeDays`를 위반한 상태에서는 적용(Apply) 버튼이 비활성화되어 `onChange`가 호출되지 않습니다. `actionArea={false}`(즉시 커밋)인 경우에도 위반 시 커밋이 취소되고 토스트만 노출됩니다.
 
 ---
 

package/dist/components/DatePicker/DatePicker.types.d.ts

@@ -68,6 +68,24 @@ interface DatePickerBaseProps {
     startLabel?: string;
     /** hasTime && (period|range)일 때 종료 시간 행의 라벨. @defaultValue `'종료'` */
     endLabel?: string;
+    /**
+     * period|range일 때 시작~종료 사이 최소 간격(분). hasTime일 때만 의미가 있다.
+     * 미지정 시 최소 간격을 검증하지 않는다.
+     */
+    minDurationMinutes?: number;
+    /**
+     * period|range일 때 시작~종료 사이 최대 일수. 미지정 시 최대 기간을 검증하지 않는다.
+     */
+    maxRangeDays?: number;
+    /**
+     * period|range && hasTime일 때, 종료 시각이 시작 시각보다 빠르면 노출되는 토스트 메시지.
+     * 미지정 시 토스트 없이 적용(Apply)만 막는다.
+     */
+    timeOrderToastText?: string;
+    /** minDurationMinutes 위반 시 노출되는 토스트 메시지. 미지정 시 토스트 없이 적용만 막는다. */
+    minDurationToastText?: string;
+    /** maxRangeDays 위반 시 노출되는 토스트 메시지. 미지정 시 토스트 없이 적용만 막는다. */
+    maxRangeToastText?: string;
     /**
      * 캘린더 헤더/월·년 선택 라벨("2026년 8월") 포맷을 재정의한다. i18n 등에 사용.
      * month는 1~12 값으로 전달된다. 미지정 시 `${year}년 ${month}월` 형식을 사용한다.

package/dist/components/DatePicker/dateUtils.d.ts

@@ -9,6 +9,8 @@ export declare function isSameDay(a: Date | null, b: Date | null): boolean;
 export declare function isSameMonth(a: Date, b: Date): boolean;
 export declare function isBefore(a: Date, b: Date): boolean;
 export declare function isAfter(a: Date, b: Date): boolean;
+/** 두 날짜의 일(day) 단위 차이. 시/분/초는 무시하고 달력 날짜만 비교한다 */
+export declare function diffInDays(a: Date, b: Date): number;
 export declare function isWithinRange(date: Date, start: Date | null, end: Date | null): boolean;
 export declare function addMonths(year: number, month: number, delta: number): {
     year: number;