@ceed/cds 1.29.1 → 1.30.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (14) hide show
  1. package/dist/components/Calendar/utils/index.d.ts +1 -0
  2. package/dist/components/DatePicker/DatePicker.d.ts +4 -0
  3. package/dist/components/DateRangePicker/DateRangePicker.d.ts +4 -0
  4. package/dist/components/MonthRangePicker/MonthRangePicker.d.ts +8 -0
  5. package/dist/components/inputs/DatePicker.md +43 -25
  6. package/dist/components/inputs/DateRangePicker.md +39 -24
  7. package/dist/components/inputs/MonthPicker.md +52 -23
  8. package/dist/components/inputs/MonthRangePicker.md +37 -21
  9. package/dist/index.browser.js +4 -4
  10. package/dist/index.browser.js.map +3 -3
  11. package/dist/index.cjs +99 -39
  12. package/dist/index.js +99 -39
  13. package/framer/index.js +1 -1
  14. package/package.json +1 -1
package/dist/components/Calendar/utils/index.d.ts CHANGED
@@ -3,6 +3,7 @@ export declare const getYearName: (date: Date, locale: string) => string;
3
3
  export declare const getMonthName: (date: Date, locale: string, options?: {
4
4
  hideYear?: boolean;
5
5
  }) => string;
6
+ export declare const getShortMonthName: (date: Date, locale: string) => string;
6
7
  export declare const getMonthNameFromIndex: (index: number, locale: string) => string;
7
8
  /**
8
9
  * 일~토 / Sun ~ Sat 같은 요일 이름을 가져옵니다.
package/dist/components/DatePicker/DatePicker.d.ts CHANGED
@@ -36,6 +36,10 @@ interface BaseDatePickerProps {
36
36
  * Input 에 표시되는 값의 포맷을 지정한다.
37
37
  */
38
38
  displayFormat?: string;
39
+ /**
40
+ * 월 이름 표시에 사용할 locale (예: 'en-US', 'ko-KR'). MMM/MMMM 토큰 사용 시 적용된다.
41
+ */
42
+ locale?: string;
39
43
  inputReadOnly?: boolean;
40
44
  hideClearButton?: boolean;
41
45
  /**
package/dist/components/DateRangePicker/DateRangePicker.d.ts CHANGED
@@ -36,6 +36,10 @@ interface BaseDateRangePickerProps {
36
36
  * Input 에 표시되는 값의 포맷을 지정한다.
37
37
  */
38
38
  displayFormat?: string;
39
+ /**
40
+ * 월 이름 표시에 사용할 locale (예: 'en-US', 'ko-KR'). MMM/MMMM 토큰 사용 시 적용된다.
41
+ */
42
+ locale?: string;
39
43
  inputReadOnly?: boolean;
40
44
  hideClearButton?: boolean;
41
45
  /**
package/dist/components/MonthRangePicker/MonthRangePicker.d.ts CHANGED
@@ -20,6 +20,14 @@ interface BaseMonthRangePickerProps {
20
20
  disableFuture?: boolean;
21
21
  disablePast?: boolean;
22
22
  format?: string;
23
+ /**
24
+ * Input 에 표시되는 값의 포맷을 지정한다.
25
+ */
26
+ displayFormat?: string;
27
+ /**
28
+ * 월 이름 표시에 사용할 locale (예: 'en-US', 'ko-KR'). MMM/MMMM 토큰 사용 시 적용된다.
29
+ */
30
+ locale?: string;
23
31
  }
24
32
  export type MonthRangePickerProps = BaseMonthRangePickerProps & Omit<React.ComponentProps<typeof Input>, 'onChange' | 'value' | 'defaultValue'>;
25
33
  declare const MonthRangePicker: React.ForwardRefExoticComponent<Omit<MonthRangePickerProps, "ref"> & React.RefAttributes<HTMLInputElement>>;
package/dist/components/inputs/DatePicker.md CHANGED
@@ -347,9 +347,7 @@ Multiple DatePicker instances can share the same value for dependent field scena
347
347
  </Stack>
348
348
  ```
349
349
 
350
- ## Common Use Cases
351
-
352
- ### Form with Validation
350
+ ## Form with Validation
353
351
 
354
352
  ```tsx
355
353
  function BookingForm() {
@@ -382,7 +380,7 @@ function BookingForm() {
382
380
  }
383
381
  ```
384
382
 
385
- ### Custom Date Disabling (Weekdays Only)
383
+ ## Custom Date Disabling (Weekdays Only)
386
384
 
387
385
  ```tsx
388
386
  function AppointmentPicker() {
@@ -406,7 +404,7 @@ function AppointmentPicker() {
406
404
  }
407
405
  ```
408
406
 
409
- ### Locale-Aware Display
407
+ ## Locale-Aware Display
410
408
 
411
409
  ```tsx
412
410
  function RegionalDateField({ locale }: { locale: string }) {
@@ -484,26 +482,27 @@ function RegionalDateField({ locale }: { locale: string }) {
484
482
 
485
483
  ### Key Props
486
484
 
487
- | Prop | Type | Default | Description |
488
- | ------------------- | ------------------------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------- |
489
- | `value` | `string` | - | Selected date string in `format` (controlled mode) |
490
- | `defaultValue` | `string` | `''` | Initial date string (uncontrolled mode) |
491
- | `onChange` | `(event: { target: { name?, value: string } }) => void` | - | Callback when the date changes. Value is in `format` |
492
- | `format` | `string` | `'YYYY/MM/DD'` | Format of the `value` and `onChange` value. Determines the internal data format |
493
- | `displayFormat` | `string` | `'YYYY/MM/DD'` | Format displayed in the input field. Can differ from `format` for locale display |
494
- | `label` | `ReactNode` | - | Form label displayed above the input |
495
- | `helperText` | `ReactNode` | - | Helper text displayed below the input |
496
- | `error` | `boolean` | `false` | Applies danger color to indicate validation error |
497
- | `required` | `boolean` | `false` | Marks the field as required (adds asterisk to label) |
498
- | `disabled` | `boolean` | `false` | Disables the entire component |
499
- | `name` | `string` | - | HTML name attribute for form submission |
500
- | `minDate` | `string` | - | Minimum selectable date (in `format`) |
501
- | `maxDate` | `string` | - | Maximum selectable date (in `format`) |
502
- | `disableFuture` | `boolean` | `false` | Disables all future dates |
503
- | `disablePast` | `boolean` | `false` | Disables all past dates |
504
- | `shouldDisableDate` | `(date: string) => boolean` | - | Custom function to disable specific dates. Receives date in `format`. Return `true` to disable |
505
- | `inputReadOnly` | `boolean` | `false` | Prevents keyboard typing in the input (users must use the calendar popup) |
506
- | `hideClearButton` | `boolean` | `false` | Hides the clear button in the calendar popup |
485
+ | Prop | Type | Default | Description |
486
+ | ------------------- | ------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
487
+ | `value` | `string` | - | Selected date string in `format` (controlled mode) |
488
+ | `defaultValue` | `string` | `''` | Initial date string (uncontrolled mode) |
489
+ | `onChange` | `(event: { target: { name?, value: string } }) => void` | - | Callback when the date changes. Value is in `format` |
490
+ | `format` | `string` | `'YYYY/MM/DD'` | Format of the `value` and `onChange` value. Determines the internal data format |
491
+ | `displayFormat` | `string` | `'YYYY/MM/DD'` | Format displayed in the input field. Can differ from `format` for locale display. Supports `MMM` (short month name) and `MMMM` (full month name) tokens |
492
+ | `locale` | `string` | `'default'` | Locale for month names when using `MMM`/`MMMM` tokens in `displayFormat` (BCP 47 format, e.g., `'en-US'`, `'ko-KR'`) |
493
+ | `label` | `ReactNode` | - | Form label displayed above the input |
494
+ | `helperText` | `ReactNode` | - | Helper text displayed below the input |
495
+ | `error` | `boolean` | `false` | Applies danger color to indicate validation error |
496
+ | `required` | `boolean` | `false` | Marks the field as required (adds asterisk to label) |
497
+ | `disabled` | `boolean` | `false` | Disables the entire component |
498
+ | `name` | `string` | - | HTML name attribute for form submission |
499
+ | `minDate` | `string` | - | Minimum selectable date (in `format`) |
500
+ | `maxDate` | `string` | - | Maximum selectable date (in `format`) |
501
+ | `disableFuture` | `boolean` | `false` | Disables all future dates |
502
+ | `disablePast` | `boolean` | `false` | Disables all past dates |
503
+ | `shouldDisableDate` | `(date: string) => boolean` | - | Custom function to disable specific dates. Receives date in `format`. Return `true` to disable |
504
+ | `inputReadOnly` | `boolean` | `false` | Prevents keyboard typing in the input (users must use the calendar popup) |
505
+ | `hideClearButton` | `boolean` | `false` | Hides the clear button in the calendar popup |
507
506
 
508
507
  ### format vs displayFormat
509
508
 
@@ -514,6 +513,25 @@ function RegionalDateField({ locale }: { locale: string }) {
514
513
 
515
514
  When both are set, the component converts between formats internally. This lets you keep a consistent API format while showing locale-appropriate display.
516
515
 
516
+ ### Alphabetic Month Tokens (MMM / MMMM)
517
+
518
+ The `displayFormat` prop supports alphabetic month tokens for more human-readable date display:
519
+
520
+ | Token | Output | Example |
521
+ | ------ | ---------------------- | ------------------------------ |
522
+ | `MMM` | Abbreviated month name | `Jan`, `Feb`, `Apr` |
523
+ | `MMMM` | Full month name | `January`, `February`, `April` |
524
+
525
+ When `displayFormat` contains `MMM` or `MMMM`, the input becomes **read-only** and the user must select a date through the calendar popup. Use the `locale` prop to control the language of month names (e.g., `locale="ko-KR"` for Korean month names).
526
+
527
+ ```tsx
528
+ <DatePicker displayFormat="MMM DD, YYYY" locale="en-US" />
529
+ // → "Apr 09, 2026"
530
+
531
+ <DatePicker displayFormat="MMMM DD, YYYY" locale="ko-KR" />
532
+ // → "4월 09, 2026"
533
+ ```
534
+
517
535
  > **Note**: DatePicker also accepts all Input props (e.g., `size`, `variant`, `color`, `startDecorator`, `placeholder`, `sx`).
518
536
 
519
537
  ## Accessibility
package/dist/components/inputs/DateRangePicker.md CHANGED
@@ -429,9 +429,7 @@ Example of integrating an external reset button to clear the selected date range
429
429
  </div>
430
430
  ```
431
431
 
432
- ## Common Use Cases
433
-
434
- ### Booking Form
432
+ ## Booking Form
435
433
 
436
434
  ```tsx
437
435
  function BookingForm() {
@@ -465,7 +463,7 @@ function BookingForm() {
465
463
  }
466
464
  ```
467
465
 
468
- ### Report Date Filter
466
+ ## Report Date Filter
469
467
 
470
468
  ```tsx
471
469
  function ReportFilters({ onFilter }) {
@@ -493,7 +491,7 @@ function ReportFilters({ onFilter }) {
493
491
  }
494
492
  ```
495
493
 
496
- ### Separate API and Display Formats
494
+ ## Separate API and Display Formats
497
495
 
498
496
  ```tsx
499
497
  function DataExport() {
@@ -566,25 +564,42 @@ const getDuration = (value) => {
566
564
 
567
565
  ### Key Props
568
566
 
569
- | Prop | Type | Default | Description |
570
- | ----------------- | ------------------------------------------------------- | -------------- | -------------------------------------------------------- |
571
- | `value` | `string` | - | Selected date range string in `format` (controlled mode) |
572
- | `defaultValue` | `string` | `''` | Initial date range string (uncontrolled mode) |
573
- | `onChange` | `(event: { target: { name?, value: string } }) => void` | - | Callback when the date range changes |
574
- | `format` | `string` | `'YYYY/MM/DD'` | Format of the `value` and `onChange` value |
575
- | `displayFormat` | `string` | `'YYYY/MM/DD'` | Format displayed in the input field |
576
- | `label` | `ReactNode` | - | Form label displayed above the input |
577
- | `helperText` | `ReactNode` | - | Helper text displayed below the input |
578
- | `error` | `boolean` | `false` | Applies danger color to indicate validation error |
579
- | `required` | `boolean` | `false` | Marks the field as required |
580
- | `disabled` | `boolean` | `false` | Disables the entire component |
581
- | `name` | `string` | - | HTML name attribute for form submission |
582
- | `minDate` | `string` | - | Minimum selectable date (in `format`) |
583
- | `maxDate` | `string` | - | Maximum selectable date (in `format`) |
584
- | `disableFuture` | `boolean` | `false` | Disables all future dates |
585
- | `disablePast` | `boolean` | `false` | Disables all past dates |
586
- | `inputReadOnly` | `boolean` | `false` | Prevents keyboard typing (calendar-only input) |
587
- | `hideClearButton` | `boolean` | `false` | Hides the clear button in the calendar popup |
567
+ | Prop | Type | Default | Description |
568
+ | ----------------- | ------------------------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------- |
569
+ | `value` | `string` | - | Selected date range string in `format` (controlled mode) |
570
+ | `defaultValue` | `string` | `''` | Initial date range string (uncontrolled mode) |
571
+ | `onChange` | `(event: { target: { name?, value: string } }) => void` | - | Callback when the date range changes |
572
+ | `format` | `string` | `'YYYY/MM/DD'` | Format of the `value` and `onChange` value |
573
+ | `displayFormat` | `string` | `'YYYY/MM/DD'` | Format displayed in the input field. Supports `MMM` (short month name) and `MMMM` (full month name) tokens |
574
+ | `locale` | `string` | `'default'` | Locale for month names when using `MMM`/`MMMM` tokens in `displayFormat` (BCP 47 format, e.g., `'en-US'`, `'ko-KR'`) |
575
+ | `label` | `ReactNode` | - | Form label displayed above the input |
576
+ | `helperText` | `ReactNode` | - | Helper text displayed below the input |
577
+ | `error` | `boolean` | `false` | Applies danger color to indicate validation error |
578
+ | `required` | `boolean` | `false` | Marks the field as required |
579
+ | `disabled` | `boolean` | `false` | Disables the entire component |
580
+ | `name` | `string` | - | HTML name attribute for form submission |
581
+ | `minDate` | `string` | - | Minimum selectable date (in `format`) |
582
+ | `maxDate` | `string` | - | Maximum selectable date (in `format`) |
583
+ | `disableFuture` | `boolean` | `false` | Disables all future dates |
584
+ | `disablePast` | `boolean` | `false` | Disables all past dates |
585
+ | `inputReadOnly` | `boolean` | `false` | Prevents keyboard typing (calendar-only input) |
586
+ | `hideClearButton` | `boolean` | `false` | Hides the clear button in the calendar popup |
587
+
588
+ ### Alphabetic Month Tokens (MMM / MMMM)
589
+
590
+ The `displayFormat` prop supports alphabetic month tokens for more human-readable date display:
591
+
592
+ | Token | Output | Example |
593
+ | ------ | ---------------------- | ------------------------------ |
594
+ | `MMM` | Abbreviated month name | `Jan`, `Feb`, `Apr` |
595
+ | `MMMM` | Full month name | `January`, `February`, `April` |
596
+
597
+ When `displayFormat` contains `MMM` or `MMMM`, the input becomes **read-only** and the user must select dates through the calendar popup. Use the `locale` prop to control the language of month names.
598
+
599
+ ```tsx
600
+ <DateRangePicker displayFormat="MMM DD, YYYY" locale="en-US" />
601
+ // → "Apr 01, 2026 - Apr 09, 2026"
602
+ ```
588
603
 
589
604
  > **Note**: DateRangePicker also accepts all Input props (e.g., `size`, `variant`, `color`, `sx`).
590
605
 
package/dist/components/inputs/MonthPicker.md CHANGED
@@ -229,6 +229,18 @@ The `displayFormat` prop controls what users see in the input field, independent
229
229
  setValue6(e.target.value);
230
230
  args.onChange?.(e);
231
231
  }} />
232
+ <MonthPicker {...args} value={value6} label="MMM YYYY" name="MMM YYYY" displayFormat="MMM YYYY" onChange={e => {
233
+ setValue6(e.target.value);
234
+ args.onChange?.(e);
235
+ }} />
236
+ <MonthPicker {...args} value={value6} label="MMM YYYY (en-US)" name="MMM YYYY (en-US)" displayFormat="MMM YYYY" locale="en-US" onChange={e => {
237
+ setValue6(e.target.value);
238
+ args.onChange?.(e);
239
+ }} />
240
+ <MonthPicker {...args} value={value6} label="MMM YYYY (ko-KR)" name="MMM YYYY (ko-KR)" displayFormat="MMM YYYY" locale="ko-KR" onChange={e => {
241
+ setValue6(e.target.value);
242
+ args.onChange?.(e);
243
+ }} />
232
244
  </Stack>
233
245
  ```
234
246
 
@@ -248,9 +260,7 @@ A controlled example with an external reset button to clear the selected value.
248
260
  </div>
249
261
  ```
250
262
 
251
- ## Common Use Cases
252
-
253
- ### Billing Period Selection
263
+ ## Billing Period Selection
254
264
 
255
265
  ```tsx
256
266
  function BillingPeriodSelector() {
@@ -268,7 +278,7 @@ function BillingPeriodSelector() {
268
278
  }
269
279
  ```
270
280
 
271
- ### Report Month Filter with Display Format
281
+ ## Report Month Filter with Display Format
272
282
 
273
283
  ```tsx
274
284
  function ReportFilter() {
@@ -286,7 +296,7 @@ function ReportFilter() {
286
296
  }
287
297
  ```
288
298
 
289
- ### Credit Card Expiry
299
+ ## Credit Card Expiry
290
300
 
291
301
  ```tsx
292
302
  function CreditCardExpiry() {
@@ -363,24 +373,43 @@ const handleChange = (e) => {
363
373
 
364
374
  ### Key Props
365
375
 
366
- | Prop | Type | Default | Description |
367
- | --------------- | ------------------------------------------------------- | -------------- | --------------------------------------------------- |
368
- | `value` | `string` | - | Selected month string in `format` (controlled mode) |
369
- | `defaultValue` | `string` | `''` | Initial month string (uncontrolled mode) |
370
- | `onChange` | `(event: { target: { name?, value: string } }) => void` | - | Callback when the month changes |
371
- | `format` | `string` | `'YYYY/MM/DD'` | Format of the `value` and `onChange` value |
372
- | `displayFormat` | `string` | `'YYYY/MM'` | Format displayed in the input field |
373
- | `label` | `ReactNode` | - | Form label displayed above the input |
374
- | `helperText` | `ReactNode` | - | Helper text displayed below the input |
375
- | `error` | `boolean` | `false` | Applies danger color to indicate validation error |
376
- | `required` | `boolean` | `false` | Marks the field as required |
377
- | `disabled` | `boolean` | `false` | Disables the entire component |
378
- | `name` | `string` | - | HTML name attribute for form submission |
379
- | `minDate` | `string` | - | Minimum selectable month (in `format`) |
380
- | `maxDate` | `string` | - | Maximum selectable month (in `format`) |
381
- | `disableFuture` | `boolean` | `false` | Disables all future months |
382
- | `disablePast` | `boolean` | `false` | Disables all past months |
383
- | `locale` | `string` | `'default'` | Locale for month names (BCP 47 format) |
376
+ | Prop | Type | Default | Description |
377
+ | --------------- | ------------------------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------- |
378
+ | `value` | `string` | - | Selected month string in `format` (controlled mode) |
379
+ | `defaultValue` | `string` | `''` | Initial month string (uncontrolled mode) |
380
+ | `onChange` | `(event: { target: { name?, value: string } }) => void` | - | Callback when the month changes |
381
+ | `format` | `string` | `'YYYY/MM/DD'` | Format of the `value` and `onChange` value |
382
+ | `displayFormat` | `string` | `'YYYY/MM'` | Format displayed in the input field. Supports `MMM` (short month name) and `MMMM` (full month name) tokens |
383
+ | `label` | `ReactNode` | - | Form label displayed above the input |
384
+ | `helperText` | `ReactNode` | - | Helper text displayed below the input |
385
+ | `error` | `boolean` | `false` | Applies danger color to indicate validation error |
386
+ | `required` | `boolean` | `false` | Marks the field as required |
387
+ | `disabled` | `boolean` | `false` | Disables the entire component |
388
+ | `name` | `string` | - | HTML name attribute for form submission |
389
+ | `minDate` | `string` | - | Minimum selectable month (in `format`) |
390
+ | `maxDate` | `string` | - | Maximum selectable month (in `format`) |
391
+ | `disableFuture` | `boolean` | `false` | Disables all future months |
392
+ | `disablePast` | `boolean` | `false` | Disables all past months |
393
+ | `locale` | `string` | `'default'` | Locale for month names (BCP 47 format) |
394
+
395
+ ### Alphabetic Month Tokens (MMM / MMMM)
396
+
397
+ The `displayFormat` prop supports alphabetic month tokens for more human-readable month display:
398
+
399
+ | Token | Output | Example |
400
+ | ------ | ---------------------- | ------------------------------ |
401
+ | `MMM` | Abbreviated month name | `Jan`, `Feb`, `Apr` |
402
+ | `MMMM` | Full month name | `January`, `February`, `April` |
403
+
404
+ Use the `locale` prop to control the language of month names.
405
+
406
+ ```tsx
407
+ <MonthPicker displayFormat="MMM YYYY" locale="en-US" />
408
+ // → "Apr 2026"
409
+
410
+ <MonthPicker displayFormat="MMMM YYYY" locale="ko-KR" />
411
+ // → "4월 2026"
412
+ ```
384
413
 
385
414
  > **Note**: MonthPicker also accepts all Input props (e.g., `size`, `variant`, `color`, `sx`).
386
415
 
package/dist/components/inputs/MonthRangePicker.md CHANGED
@@ -217,9 +217,7 @@ A controlled example with an external reset button to clear the selected range.
217
217
  </div>
218
218
  ```
219
219
 
220
- ## Common Use Cases
221
-
222
- ### Fiscal Period Report
220
+ ## Fiscal Period Report
223
221
 
224
222
  ```tsx
225
223
  function FiscalReportSelector() {
@@ -248,7 +246,7 @@ function FiscalReportSelector() {
248
246
  }
249
247
  ```
250
248
 
251
- ### Subscription Duration with Month Count
249
+ ## Subscription Duration with Month Count
252
250
 
253
251
  ```tsx
254
252
  function SubscriptionForm() {
@@ -279,7 +277,7 @@ function SubscriptionForm() {
279
277
  }
280
278
  ```
281
279
 
282
- ### Year-over-Year Comparison
280
+ ## Year-over-Year Comparison
283
281
 
284
282
  ```tsx
285
283
  function YearOverYearComparison() {
@@ -367,22 +365,40 @@ const handleSubmit = () => {
367
365
 
368
366
  ### Key Props
369
367
 
370
- | Prop | Type | Default | Description |
371
- | --------------- | ------------------------------------------------------- | ----------- | --------------------------------------------------------- |
372
- | `value` | `string` | - | Selected month range string in `format` (controlled mode) |
373
- | `defaultValue` | `string` | `''` | Initial month range string (uncontrolled mode) |
374
- | `onChange` | `(event: { target: { name?, value: string } }) => void` | - | Callback when the month range changes |
375
- | `format` | `string` | `'YYYY/MM'` | Format of the `value` and `onChange` value |
376
- | `label` | `ReactNode` | - | Form label displayed above the input |
377
- | `helperText` | `ReactNode` | - | Helper text displayed below the input |
378
- | `error` | `boolean` | `false` | Applies danger color to indicate validation error |
379
- | `required` | `boolean` | `false` | Marks the field as required |
380
- | `disabled` | `boolean` | `false` | Disables the entire component |
381
- | `name` | `string` | - | HTML name attribute for form submission |
382
- | `minDate` | `string` | - | Minimum selectable month (in `format`) |
383
- | `maxDate` | `string` | - | Maximum selectable month (in `format`) |
384
- | `disableFuture` | `boolean` | `false` | Disables all future months |
385
- | `disablePast` | `boolean` | `false` | Disables all past months |
368
+ | Prop | Type | Default | Description |
369
+ | --------------- | ------------------------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------- |
370
+ | `value` | `string` | - | Selected month range string in `format` (controlled mode) |
371
+ | `defaultValue` | `string` | `''` | Initial month range string (uncontrolled mode) |
372
+ | `onChange` | `(event: { target: { name?, value: string } }) => void` | - | Callback when the month range changes |
373
+ | `format` | `string` | `'YYYY/MM'` | Format of the `value` and `onChange` value |
374
+ | `displayFormat` | `string` | same as `format` | Format displayed in the input field. Supports `MMM` (short month name) and `MMMM` (full month name) tokens |
375
+ | `locale` | `string` | `'default'` | Locale for month names when using `MMM`/`MMMM` tokens in `displayFormat` (BCP 47 format, e.g., `'en-US'`, `'ko-KR'`) |
376
+ | `label` | `ReactNode` | - | Form label displayed above the input |
377
+ | `helperText` | `ReactNode` | - | Helper text displayed below the input |
378
+ | `error` | `boolean` | `false` | Applies danger color to indicate validation error |
379
+ | `required` | `boolean` | `false` | Marks the field as required |
380
+ | `disabled` | `boolean` | `false` | Disables the entire component |
381
+ | `name` | `string` | - | HTML name attribute for form submission |
382
+ | `minDate` | `string` | - | Minimum selectable month (in `format`) |
383
+ | `maxDate` | `string` | - | Maximum selectable month (in `format`) |
384
+ | `disableFuture` | `boolean` | `false` | Disables all future months |
385
+ | `disablePast` | `boolean` | `false` | Disables all past months |
386
+
387
+ ### Alphabetic Month Tokens (MMM / MMMM)
388
+
389
+ The `displayFormat` prop supports alphabetic month tokens for more human-readable month display:
390
+
391
+ | Token | Output | Example |
392
+ | ------ | ---------------------- | ------------------------------ |
393
+ | `MMM` | Abbreviated month name | `Jan`, `Feb`, `Apr` |
394
+ | `MMMM` | Full month name | `January`, `February`, `April` |
395
+
396
+ When `displayFormat` contains `MMM` or `MMMM`, the input becomes **read-only** and the user must select months through the calendar popup. Use the `locale` prop to control the language of month names.
397
+
398
+ ```tsx
399
+ <MonthRangePicker displayFormat="MMM YYYY" locale="en-US" />
400
+ // → "Apr 2026 - May 2026"
401
+ ```
386
402
 
387
403
  > **Note**: MonthRangePicker also accepts all Input props (e.g., `size`, `variant`, `color`, `sx`).
388
404