@ceed/ads 1.30.0 → 1.31.0

package/dist/components/inputs/Input.md

@@ -1,11 +1,8 @@
 # Input
 
-Input 컴포넌트는 사용자로부터 텍스트 입력을 받기 위한 기본 컴포넌트입니다. 다양한 스타일, 크기 및 기능을 지원합니다.
+## Introduction
 
-> 💡 **Form 구성 시 내장 prop 사용을 권장합니다**
->
-> 이 컴포넌트는 `label`, `helperText` 등의 Form 요소를 자체적으로 지원합니다.
-> Form을 구성할 때 Typography로 별도의 label이나 helperText를 만드는 대신, 컴포넌트의 내장 prop을 사용하세요.
+Input is a single-line text field component for capturing user input. Built on Joy UI's Input with Framer Motion animation support, it includes built-in form field composition (`label`, `helperText`, `error`) so you can build complete form fields without manual `FormControl` wrappers. It supports clearable inputs, password visibility toggling, and start/end decorators.
 
 ```tsx
 <Input />
@@ -34,17 +31,33 @@ Input 컴포넌트는 사용자로부터 텍스트 입력을 받기 위한 기
 | sx                          | —           | —       |
 | className                   | —           | —       |
 
-## 기본형
+> **Use built-in form props**
+>
+> This component natively supports `label` and `helperText` props.
+> When building forms, use these built-in props instead of manually composing labels and helper text with Typography.
 
-Input의 기본 형태입니다. 사용자의 텍스트 입력을 받는 단일 라인 필드입니다.
+## Usage
 
 ```tsx
-<Input />
+import { Input } from '@ceed/ads';
+
+function MyComponent() {
+  const [value, setValue] = useState('');
+
+  return (
+    <Input
+      label="Name"
+      placeholder="Enter your name"
+      value={value}
+      onChange={(e) => setValue(e.target.value)}
+    />
+  );
+}
 ```
 
-## 변형(Variants)
+## Variants
 
-Input은 네 가지 변형을 지원합니다: `solid`, `soft`, `outlined`, `plain`
+Input supports four visual styles: `outlined` (default), `solid`, `soft`, and `plain`.
 
 ```tsx
 <>
@@ -55,9 +68,9 @@ Input은 네 가지 변형을 지원합니다: `solid`, `soft`, `outlined`, `pla
 </>
 ```
 
-## 크기(Sizes)
+## Sizes
 
-Input은 세 가지 크기를 지원합니다: `sm`, `md`, `lg`
+Three sizes are available: `sm`, `md` (default), and `lg`.
 
 ```tsx
 <>
@@ -67,13 +80,11 @@ Input은 세 가지 크기를 지원합니다: `sm`, `md`, `lg`
 </>
 ```
 
-## 레이블 및 도움말 텍스트
-
-Input 컴포넌트에 `label`과 `helperText` 속성을 추가하여 사용자에게 추가 정보를 제공할 수 있습니다.
+## Label and Helper Text
 
-### 레이블(Label)
+### Label
 
-`label` 속성을 사용하여 Input 위에 레이블을 표시할 수 있습니다.
+The `label` prop renders a form label above the input.
 
 ```tsx
 <>
@@ -81,9 +92,9 @@ Input 컴포넌트에 `label`과 `helperText` 속성을 추가하여 사용자
 </>
 ```
 
-### 도움말 텍스트(Helper Text)
+### Helper Text
 
-`helperText` 속성을 사용하여 Input 아래에 추가 정보를 제공할 수 있습니다.
+The `helperText` prop renders descriptive text below the input.
 
 ```tsx
 <>
@@ -91,19 +102,19 @@ Input 컴포넌트에 `label`과 `helperText` 속성을 추가하여 사용자
 </>
 ```
 
-## 상태(States)
+## States
 
-### 비활성화(Disabled)
+### Disabled
 
-`disabled` 속성을 사용하여 Input을 비활성화할 수 있습니다.
+A disabled input cannot be focused or interacted with.
 
 ```tsx
 <Input disabled />
 ```
 
-### 오류 상태(Error)
+### Error
 
-`error` 속성을 사용하여 오류 상태를 표시할 수 있습니다.
+Set `error` to visually indicate a validation failure. Combine with `helperText` to display an error message.
 
 ```tsx
 <>
@@ -111,9 +122,9 @@ Input 컴포넌트에 `label`과 `helperText` 속성을 추가하여 사용자
 </>
 ```
 
-### 필수 값(Required)
+### Required
 
-`required` 속성을 사용하여 필수 입력 필드임을 표시할 수 있습니다.
+Set `required` to mark the field as required. An asterisk is added to the label automatically.
 
 ```tsx
 <Input
@@ -124,9 +135,9 @@ Input 컴포넌트에 `label`과 `helperText` 속성을 추가하여 사용자
 />
 ```
 
-## 장식자(Decorators)
+## Decorators
 
-Input 컴포넌트는 `startDecorator`와 `endDecorator` 속성을 통해 입력 필드의 시작과 끝 부분에 아이콘, 버튼 또는 기타 요소를 추가할 수 있습니다.
+Use `startDecorator` and `endDecorator` to add icons, buttons, or other elements at the start or end of the input field.
 
 ```tsx
 <Stack spacing={3}>
@@ -166,7 +177,7 @@ width: 300
 </Stack>
 ```
 
-`endDecorator`와 `enableClearable`을 함께 사용하면 다음과 같습니다:
+When using `endDecorator` together with `enableClearable`, both elements are displayed side by side:
 
 ```tsx
 <Input
@@ -177,9 +188,9 @@ width: 300
 />
 ```
 
-## 지울 수 있는 입력(Clearable Input)
+## Clearable Input
 
-`enableClearable` 속성을 사용하여 Input에 내용을 지울 수 있는 버튼을 추가할 수 있습니다.
+Set `enableClearable` to show a clear button when the input has a value. Clicking the button clears the input content.
 
 ```tsx
 <>
@@ -187,9 +198,16 @@ width: 300
 </>
 ```
 
-## 비밀번호 입력(Password Input)
+```tsx
+<Input
+  enableClearable
+  placeholder="Type something and clear it"
+/>
+```
+
+## Password Input
 
-`type="password"` 속성을 사용하면 비밀번호 입력 필드가 생성되며, 자동으로 비밀번호 표시/숨김 토글 버튼이 추가됩니다.
+Setting `type="password"` creates a password field with an automatic visibility toggle button.
 
 ```tsx
 <Stack spacing={3}>
@@ -204,26 +222,17 @@ width: 300
 </Stack>
 ```
 
-### 비밀번호 토글 비활성화
+### Disabling the Password Toggle
 
-비밀번호 입력 필드의 토글 버튼은 `disableTogglePasswordButton` 속성을 사용하여 비활성화할 수 있습니다.
+Use `disableTogglePasswordButton` to hide the visibility toggle button on password inputs.
 
 ```tsx
-<Stack spacing={3}>
-  <Typography level="body-md">Default password input with toggle button:</Typography>
-  <Input {...args} placeholder="Enter password" type="password" label="Password" />
-
-  <Typography level="body-md">Disabled password input:</Typography>
-  <Input {...args} placeholder="Enter password" type="password" label="Disabled Password" disabled />
-
-  <Typography level="body-md">Password input with toggle button disabled:</Typography>
-  <Input {...args} placeholder="Enter password" type="password" label="No Toggle" disableTogglePasswordButton />
-</Stack>
+<Input type="password" disableTogglePasswordButton placeholder="Password" />
 ```
 
-### 비밀번호 입력의 제한 사항
+### Password Input Limitations
 
-비밀번호 입력 필드(`type="password"`)에서는 `endDecorator`를 사용할 수 없습니다. 이는 비밀번호 토글 버튼이 해당 위치를 차지하기 때문입니다.
+Password inputs (`type="password"`) do not support custom `endDecorator` because the password toggle button occupies that slot. If you provide `endDecorator` with a password input, the component logs a warning and ignores it.
 
 ```tsx
 <Stack spacing={3}>
@@ -235,9 +244,9 @@ width: 300
 </Stack>
 ```
 
-## 폼 컨트롤(Form Control)
+## Form Control
 
-Input 컴포넌트는 `label`, `helperText`, `error` 속성을 조합하여 완전한 폼 컨트롤을 구성할 수 있습니다.
+Combining `label`, `helperText`, and `error` produces a complete form field.
 
 ```tsx
 <>
@@ -246,11 +255,25 @@ Input 컴포넌트는 `label`, `helperText`, `error` 속성을 조합하여 완
 </>
 ```
 
-## 상태 관리
+```tsx
+<Input
+  label="Email"
+  helperText="We'll never share your email"
+  required
+/>
+
+<Input
+  label="Email"
+  error
+  helperText="Invalid email address"
+/>
+```
+
+## Controlled / Uncontrolled
 
-### 제어 컴포넌트(Controlled Component)
+### Controlled
 
-Input은 React의 제어 컴포넌트로 사용할 수 있습니다. `value`와 `onChange` 속성을 사용하여 상태를 관리합니다.
+Use `value` and `onChange` for controlled behavior.
 
 ```tsx
 <>
@@ -258,31 +281,194 @@ Input은 React의 제어 컴포넌트로 사용할 수 있습니다. `value`와
 </>
 ```
 
-### 비제어 컴포넌트(Uncontrolled Component)
+```tsx
+const [value, setValue] = useState('');
+
+<Input
+  value={value}
+  onChange={(e) => setValue(e.target.value)}
+  placeholder="Controlled input"
+/>
+```
+
+### Uncontrolled
+
+Use `defaultValue` for uncontrolled behavior.
+
+```tsx
+<Input defaultValue="Initial value" placeholder="Uncontrolled input" />
+```
+
+## Search Field
+
+```tsx
+import { Input } from '@ceed/ads';
+import SearchIcon from '@mui/icons-material/Search';
+
+function SearchField({ onSearch }) {
+  const [query, setQuery] = useState('');
+
+  return (
+    <Input
+      placeholder="Search..."
+      startDecorator={<SearchIcon />}
+      enableClearable
+      value={query}
+      onChange={(e) => {
+        setQuery(e.target.value);
+        onSearch(e.target.value);
+      }}
+    />
+  );
+}
+```
+
+## Login Form
+
+```tsx
+import { Input, Button, Stack } from '@ceed/ads';
+
+function LoginForm({ onSubmit }) {
+  return (
+    <form onSubmit={onSubmit}>
+      <Stack spacing={2}>
+        <Input
+          label="Email"
+          type="email"
+          required
+          placeholder="Enter your email"
+        />
+        <Input
+          label="Password"
+          type="password"
+          required
+          placeholder="Enter your password"
+        />
+        <Button type="submit">Sign In</Button>
+      </Stack>
+    </form>
+  );
+}
+```
+
+## Form with Validation
 
-`defaultValue` 속성을 사용하여 비제어 컴포넌트로도 사용 가능합니다.
+```tsx
+import { useState } from 'react';
+import { Input, Button, Stack } from '@ceed/ads';
+
+function ValidatedForm() {
+  const [email, setEmail] = useState('');
+  const [submitted, setSubmitted] = useState(false);
+  const isValid = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+
+  return (
+    <form onSubmit={(e) => { e.preventDefault(); setSubmitted(true); }}>
+      <Stack spacing={2}>
+        <Input
+          label="Email"
+          required
+          value={email}
+          onChange={(e) => setEmail(e.target.value)}
+          error={submitted && !isValid}
+          helperText={submitted && !isValid ? 'Please enter a valid email' : undefined}
+          placeholder="user@example.com"
+        />
+        <Button type="submit">Submit</Button>
+      </Stack>
+    </form>
+  );
+}
+```
 
-## 접근성(Accessibility)
+## Props and Customization
+
+### Key Props
+
+| Prop                          | Type                                                           | Default      | Description                                                                     |
+| ----------------------------- | -------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------- |
+| `label`                       | `ReactNode`                                                    | -            | Label text displayed above the input                                            |
+| `helperText`                  | `ReactNode`                                                    | -            | Helper text displayed below the input                                           |
+| `error`                       | `boolean`                                                      | `false`      | Applies danger color to indicate validation error                               |
+| `enableClearable`             | `boolean`                                                      | `false`      | Shows a clear button when the input has a value                                 |
+| `disableTogglePasswordButton` | `boolean`                                                      | `false`      | Hides the password visibility toggle (only applies when `type="password"`)      |
+| `value`                       | `string`                                                       | -            | Input value for controlled mode                                                 |
+| `defaultValue`                | `string`                                                       | -            | Initial value for uncontrolled mode                                             |
+| `onChange`                    | `(event: ChangeEvent<HTMLInputElement>) => void`               | -            | Callback when the input value changes                                           |
+| `placeholder`                 | `string`                                                       | -            | Placeholder text when the input is empty                                        |
+| `type`                        | `string`                                                       | `'text'`     | HTML input type (`text`, `password`, `email`, `number`, etc.)                   |
+| `disabled`                    | `boolean`                                                      | `false`      | Disables the input                                                              |
+| `readOnly`                    | `boolean`                                                      | `false`      | Makes the input read-only (focusable but not editable)                          |
+| `required`                    | `boolean`                                                      | `false`      | Marks the field as required (adds asterisk to label)                            |
+| `name`                        | `string`                                                       | -            | HTML name attribute for form submission                                         |
+| `size`                        | `'sm' \| 'md' \| 'lg'`                                         | `'md'`       | Input size                                                                      |
+| `variant`                     | `'outlined' \| 'solid' \| 'soft' \| 'plain'`                   | `'outlined'` | Visual style variant                                                            |
+| `color`                       | `'primary' \| 'neutral' \| 'danger' \| 'success' \| 'warning'` | `'neutral'`  | Color scheme                                                                    |
+| `startDecorator`              | `ReactNode`                                                    | -            | Content rendered at the start of the input                                      |
+| `endDecorator`                | `ReactNode`                                                    | -            | Content rendered at the end of the input (not supported with `type="password"`) |
+| `sx`                          | `SxProps`                                                      | -            | Custom styles using the MUI system                                              |
+
+> **Note**: Input also accepts all Joy UI Input props and Framer Motion props.
+
+## Best Practices
+
+1. **Use built-in `label` and `helperText`** instead of wrapping with FormControl manually.
 
-Input 컴포넌트는 웹 접근성 표준을 준수합니다:
+```tsx
+// ✅ Good
+<Input label="Email" helperText="Enter your work email" />
+
+// ❌ Bad
+<FormControl>
+  <FormLabel>Email</FormLabel>
+  <Input />
+  <FormHelperText>Enter your work email</FormHelperText>
+</FormControl>
+```
 
-- 적절한 레이블과 연결되어 있습니다.
-- 키보드 탐색이 가능합니다.
-- 오류 상태는 시각적으로 명확하게 표시됩니다.
+2. **Choose the right input type** for the data being captured.
 
-## 테스팅(Testing)
+```tsx
+// ✅ Good: Appropriate types
+<Input type="email" label="Email" />
+<Input type="password" label="Password" />
+<Input type="tel" label="Phone" />
 
-### Testing Library 참고사항
+// ❌ Bad: Generic text for everything
+<Input type="text" label="Email" />
+```
 
-- `type="password"` 속성을 가진 Input을 Testing Library로 찾을 때는 항상 `textbox` 역할(role)로 찾아야 합니다.
-- 이는 ARIA 명세에 따라 `password` 입력이 특별한 role을 갖지 않고 기본적으로 `textbox` role을 사용하기 때문입니다.
+3. **Always provide labels** for accessibility. If a visible label is not appropriate, use `aria-label`.
 
 ```tsx
-// 비밀번호 입력 필드를 찾는 예시
-const passwordInput = screen.getByRole('textbox', { name: /비밀번호/i });
+// ✅ Good: Visible label
+<Input label="Search" />
+
+// ✅ Good: Hidden label for icon-only inputs
+<Input aria-label="Search" startDecorator={<SearchIcon />} />
+
+// ❌ Bad: No label at all
+<Input placeholder="Search..." />
 ```
 
-**참고 이슈:**
+4. **Use `enableClearable` for search and filter inputs** where users frequently need to clear and re-enter values.
+
+5. **Do not use `endDecorator` with password inputs.** The password toggle button occupies the end slot. Use `startDecorator` instead for additional icons.
+
+## Accessibility
+
+- **Label association**: The `label` prop automatically connects the label to the input via `htmlFor`/`id` pairing.
+- **Keyboard navigation**: Standard keyboard support — Tab to focus, type to input, Escape to blur (when applicable).
+- **Error announcement**: When `error` is set, `aria-invalid` is applied. Pair with `helperText` so assistive technology announces the error.
+- **Required state**: The `required` prop adds `aria-required` and a visible asterisk to the label.
+- **Password toggle**: The visibility toggle button is keyboard-accessible and includes an appropriate `aria-label`.
+
+## Testing Notes
+
+When using Testing Library, always query password inputs by `textbox` role:
+
+```tsx
+const passwordInput = screen.getByRole('textbox', { name: /password/i });
+```
 
-- [W3C ARIA: Should there be a role=password?](https://github.com/w3c/aria/issues/935)
-- [Testing Library: How to find password inputs](https://github.com/testing-library/dom-testing-library/issues/567)
+This is because the ARIA specification does not define a `password` role — password inputs use the default `textbox` role.

package/dist/components/inputs/MonthPicker.md

@@ -229,6 +229,18 @@ The `displayFormat` prop controls what users see in the input field, independent
     setValue6(e.target.value);
     args.onChange?.(e);
   }} />
+  <MonthPicker {...args} value={value6} label="MMM YYYY" name="MMM YYYY" displayFormat="MMM YYYY" onChange={e => {
+    setValue6(e.target.value);
+    args.onChange?.(e);
+  }} />
+  <MonthPicker {...args} value={value6} label="MMM YYYY (en-US)" name="MMM YYYY (en-US)" displayFormat="MMM YYYY" locale="en-US" onChange={e => {
+    setValue6(e.target.value);
+    args.onChange?.(e);
+  }} />
+  <MonthPicker {...args} value={value6} label="MMM YYYY (ko-KR)" name="MMM YYYY (ko-KR)" displayFormat="MMM YYYY" locale="ko-KR" onChange={e => {
+    setValue6(e.target.value);
+    args.onChange?.(e);
+  }} />
 </Stack>
 ```
 
@@ -248,9 +260,7 @@ A controlled example with an external reset button to clear the selected value.
 </div>
 ```
 
-## Common Use Cases
-
-### Billing Period Selection
+## Billing Period Selection
 
 ```tsx
 function BillingPeriodSelector() {
@@ -268,7 +278,7 @@ function BillingPeriodSelector() {
 }
 ```
 
-### Report Month Filter with Display Format
+## Report Month Filter with Display Format
 
 ```tsx
 function ReportFilter() {
@@ -286,7 +296,7 @@ function ReportFilter() {
 }
 ```
 
-### Credit Card Expiry
+## Credit Card Expiry
 
 ```tsx
 function CreditCardExpiry() {
@@ -359,6 +369,50 @@ const handleChange = (e) => {
 };
 ```
 
+## Props and Customization
+
+### Key Props
+
+| Prop            | Type                                                    | Default        | Description                                                                                                |
+| --------------- | ------------------------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------- |
+| `value`         | `string`                                                | -              | Selected month string in `format` (controlled mode)                                                        |
+| `defaultValue`  | `string`                                                | `''`           | Initial month string (uncontrolled mode)                                                                   |
+| `onChange`      | `(event: { target: { name?, value: string } }) => void` | -              | Callback when the month changes                                                                            |
+| `format`        | `string`                                                | `'YYYY/MM/DD'` | Format of the `value` and `onChange` value                                                                 |
+| `displayFormat` | `string`                                                | `'YYYY/MM'`    | Format displayed in the input field. Supports `MMM` (short month name) and `MMMM` (full month name) tokens |
+| `label`         | `ReactNode`                                             | -              | Form label displayed above the input                                                                       |
+| `helperText`    | `ReactNode`                                             | -              | Helper text displayed below the input                                                                      |
+| `error`         | `boolean`                                               | `false`        | Applies danger color to indicate validation error                                                          |
+| `required`      | `boolean`                                               | `false`        | Marks the field as required                                                                                |
+| `disabled`      | `boolean`                                               | `false`        | Disables the entire component                                                                              |
+| `name`          | `string`                                                | -              | HTML name attribute for form submission                                                                    |
+| `minDate`       | `string`                                                | -              | Minimum selectable month (in `format`)                                                                     |
+| `maxDate`       | `string`                                                | -              | Maximum selectable month (in `format`)                                                                     |
+| `disableFuture` | `boolean`                                               | `false`        | Disables all future months                                                                                 |
+| `disablePast`   | `boolean`                                               | `false`        | Disables all past months                                                                                   |
+| `locale`        | `string`                                                | `'default'`    | Locale for month names (BCP 47 format)                                                                     |
+
+### Alphabetic Month Tokens (MMM / MMMM)
+
+The `displayFormat` prop supports alphabetic month tokens for more human-readable month display:
+
+| Token  | Output                 | Example                        |
+| ------ | ---------------------- | ------------------------------ |
+| `MMM`  | Abbreviated month name | `Jan`, `Feb`, `Apr`            |
+| `MMMM` | Full month name        | `January`, `February`, `April` |
+
+Use the `locale` prop to control the language of month names.
+
+```tsx
+<MonthPicker displayFormat="MMM YYYY" locale="en-US" />
+// → "Apr 2026"
+
+<MonthPicker displayFormat="MMMM YYYY" locale="ko-KR" />
+// → "4월 2026"
+```
+
+> **Note**: MonthPicker also accepts all Input props (e.g., `size`, `variant`, `color`, `sx`).
+
 ## Accessibility
 
 - The input has `role="textbox"` and the calendar toggle button has `aria-label="Toggle Calendar"` for screen reader identification.

package/dist/components/inputs/MonthRangePicker.md

@@ -217,9 +217,7 @@ A controlled example with an external reset button to clear the selected range.
 </div>
 ```
 
-## Common Use Cases
-
-### Fiscal Period Report
+## Fiscal Period Report
 
 ```tsx
 function FiscalReportSelector() {
@@ -248,7 +246,7 @@ function FiscalReportSelector() {
 }
 ```
 
-### Subscription Duration with Month Count
+## Subscription Duration with Month Count
 
 ```tsx
 function SubscriptionForm() {
@@ -279,7 +277,7 @@ function SubscriptionForm() {
 }
 ```
 
-### Year-over-Year Comparison
+## Year-over-Year Comparison
 
 ```tsx
 function YearOverYearComparison() {
@@ -363,6 +361,47 @@ const handleSubmit = () => {
 <MonthRangePicker format="YYYY-MM" />
 ```
 
+## Props and Customization
+
+### Key Props
+
+| Prop            | Type                                                    | Default          | Description                                                                                                          |
+| --------------- | ------------------------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `value`         | `string`                                                | -                | Selected month range string in `format` (controlled mode)                                                            |
+| `defaultValue`  | `string`                                                | `''`             | Initial month range string (uncontrolled mode)                                                                       |
+| `onChange`      | `(event: { target: { name?, value: string } }) => void` | -                | Callback when the month range changes                                                                                |
+| `format`        | `string`                                                | `'YYYY/MM'`      | Format of the `value` and `onChange` value                                                                           |
+| `displayFormat` | `string`                                                | same as `format` | Format displayed in the input field. Supports `MMM` (short month name) and `MMMM` (full month name) tokens           |
+| `locale`        | `string`                                                | `'default'`      | Locale for month names when using `MMM`/`MMMM` tokens in `displayFormat` (BCP 47 format, e.g., `'en-US'`, `'ko-KR'`) |
+| `label`         | `ReactNode`                                             | -                | Form label displayed above the input                                                                                 |
+| `helperText`    | `ReactNode`                                             | -                | Helper text displayed below the input                                                                                |
+| `error`         | `boolean`                                               | `false`          | Applies danger color to indicate validation error                                                                    |
+| `required`      | `boolean`                                               | `false`          | Marks the field as required                                                                                          |
+| `disabled`      | `boolean`                                               | `false`          | Disables the entire component                                                                                        |
+| `name`          | `string`                                                | -                | HTML name attribute for form submission                                                                              |
+| `minDate`       | `string`                                                | -                | Minimum selectable month (in `format`)                                                                               |
+| `maxDate`       | `string`                                                | -                | Maximum selectable month (in `format`)                                                                               |
+| `disableFuture` | `boolean`                                               | `false`          | Disables all future months                                                                                           |
+| `disablePast`   | `boolean`                                               | `false`          | Disables all past months                                                                                             |
+
+### Alphabetic Month Tokens (MMM / MMMM)
+
+The `displayFormat` prop supports alphabetic month tokens for more human-readable month display:
+
+| Token  | Output                 | Example                        |
+| ------ | ---------------------- | ------------------------------ |
+| `MMM`  | Abbreviated month name | `Jan`, `Feb`, `Apr`            |
+| `MMMM` | Full month name        | `January`, `February`, `April` |
+
+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.
+
+```tsx
+<MonthRangePicker displayFormat="MMM YYYY" locale="en-US" />
+// → "Apr 2026 - May 2026"
+```
+
+> **Note**: MonthRangePicker also accepts all Input props (e.g., `size`, `variant`, `color`, `sx`).
+
 ## Accessibility
 
 - The input has `role="textbox"` and the calendar toggle button has `aria-label="Toggle Calendar"` for screen reader identification.