@ceed/cds 1.29.0 → 1.30.0

package/dist/components/inputs/CurrencyInput.md

@@ -261,6 +261,28 @@ function BudgetSetting() {
 
 5. **Handle negative values carefully**: CurrencyInput supports negative values. If negatives are not valid for your use case, validate in `onChange`.
 
+## Props and Customization
+
+### Key Props
+
+| Prop           | Type                                                     | Default | Description                                              |
+| -------------- | -------------------------------------------------------- | ------- | -------------------------------------------------------- |
+| `value`        | `number`                                                 | -       | Currency value (controlled mode)                         |
+| `defaultValue` | `number`                                                 | -       | Initial currency value (uncontrolled mode)               |
+| `onChange`     | `(event: { target: { name?, value?: number } }) => void` | -       | Callback when the value changes                          |
+| `currency`     | `'USD' \| 'KRW' \| 'CAD'`                                | `'USD'` | Currency code (determines symbol and formatting)         |
+| `useMinorUnit` | `boolean`                                                | `false` | When true, value is in minor units (e.g., cents for USD) |
+| `max`          | `number`                                                 | -       | Maximum allowed value                                    |
+| `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 input                                       |
+| `name`         | `string`                                                 | -       | HTML name attribute for form submission                  |
+| `placeholder`  | `string`                                                 | -       | Placeholder text when the input is empty                 |
+| `size`         | `'sm' \| 'md' \| 'lg'`                                   | `'md'`  | Input size                                               |
+| `sx`           | `SxProps`                                                | -       | Custom styles using the MUI system                       |
+
 ## Accessibility
 
 - The input has `role="textbox"` with proper labeling via the `label` prop.

package/dist/components/inputs/DatePicker.md

@@ -347,9 +347,7 @@ Multiple DatePicker instances can share the same value for dependent field scena
 </Stack>
 ```
 
-## Common Use Cases
-
-### Form with Validation
+## Form with Validation
 
 ```tsx
 function BookingForm() {
@@ -382,7 +380,7 @@ function BookingForm() {
 }
 ```
 
-### Custom Date Disabling (Weekdays Only)
+## Custom Date Disabling (Weekdays Only)
 
 ```tsx
 function AppointmentPicker() {
@@ -406,7 +404,7 @@ function AppointmentPicker() {
 }
 ```
 
-### Locale-Aware Display
+## Locale-Aware Display
 
 ```tsx
 function RegionalDateField({ locale }: { locale: string }) {
@@ -480,6 +478,62 @@ function RegionalDateField({ locale }: { locale: string }) {
 <DatePicker value={invalidDate} />
 ```
 
+## Props and Customization
+
+### Key Props
+
+| Prop                | Type                                                    | Default        | Description                                                                                                                                             |
+| ------------------- | ------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `value`             | `string`                                                | -              | Selected date string in `format` (controlled mode)                                                                                                      |
+| `defaultValue`      | `string`                                                | `''`           | Initial date string (uncontrolled mode)                                                                                                                 |
+| `onChange`          | `(event: { target: { name?, value: string } }) => void` | -              | Callback when the date changes. Value is in `format`                                                                                                    |
+| `format`            | `string`                                                | `'YYYY/MM/DD'` | Format of the `value` and `onChange` value. Determines the internal data format                                                                         |
+| `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 |
+| `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 (adds asterisk to label)                                                                                                    |
+| `disabled`          | `boolean`                                               | `false`        | Disables the entire component                                                                                                                           |
+| `name`              | `string`                                                | -              | HTML name attribute for form submission                                                                                                                 |
+| `minDate`           | `string`                                                | -              | Minimum selectable date (in `format`)                                                                                                                   |
+| `maxDate`           | `string`                                                | -              | Maximum selectable date (in `format`)                                                                                                                   |
+| `disableFuture`     | `boolean`                                               | `false`        | Disables all future dates                                                                                                                               |
+| `disablePast`       | `boolean`                                               | `false`        | Disables all past dates                                                                                                                                 |
+| `shouldDisableDate` | `(date: string) => boolean`                             | -              | Custom function to disable specific dates. Receives date in `format`. Return `true` to disable                                                          |
+| `inputReadOnly`     | `boolean`                                               | `false`        | Prevents keyboard typing in the input (users must use the calendar popup)                                                                               |
+| `hideClearButton`   | `boolean`                                               | `false`        | Hides the clear button in the calendar popup                                                                                                            |
+
+### format vs displayFormat
+
+| Prop            | Controls                                               | Example                                           |
+| --------------- | ------------------------------------------------------ | ------------------------------------------------- |
+| `format`        | Value in `onChange`, `value`, and `defaultValue` props | `'YYYY-MM-DD'` → onChange receives `'2024-05-03'` |
+| `displayFormat` | What the user sees in the input field                  | `'MM/DD/YYYY'` → input shows `05/03/2024`         |
+
+When both are set, the component converts between formats internally. This lets you keep a consistent API format while showing locale-appropriate display.
+
+### Alphabetic Month Tokens (MMM / MMMM)
+
+The `displayFormat` prop supports alphabetic month tokens for more human-readable date 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 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).
+
+```tsx
+<DatePicker displayFormat="MMM DD, YYYY" locale="en-US" />
+// → "Apr 09, 2026"
+
+<DatePicker displayFormat="MMMM DD, YYYY" locale="ko-KR" />
+// → "4월 09, 2026"
+```
+
+> **Note**: DatePicker also accepts all Input props (e.g., `size`, `variant`, `color`, `startDecorator`, `placeholder`, `sx`).
+
 ## Accessibility
 
 - **Keyboard navigation**: Tab moves focus between the input and the calendar toggle button. Arrow keys navigate dates within the open calendar. Enter selects the focused date, and Escape closes the calendar popup.

package/dist/components/inputs/DateRangePicker.md

@@ -429,9 +429,7 @@ Example of integrating an external reset button to clear the selected date range
 </div>
 ```
 
-## Common Use Cases
-
-### Booking Form
+## Booking Form
 
 ```tsx
 function BookingForm() {
@@ -465,7 +463,7 @@ function BookingForm() {
 }
 ```
 
-### Report Date Filter
+## Report Date Filter
 
 ```tsx
 function ReportFilters({ onFilter }) {
@@ -493,7 +491,7 @@ function ReportFilters({ onFilter }) {
 }
 ```
 
-### Separate API and Display Formats
+## Separate API and Display Formats
 
 ```tsx
 function DataExport() {
@@ -562,6 +560,49 @@ const getDuration = (value) => {
 <DateRangePicker helperText={getDuration(dateRange)} />
 ```
 
+## Props and Customization
+
+### Key Props
+
+| Prop              | Type                                                    | Default        | Description                                                                                                          |
+| ----------------- | ------------------------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `value`           | `string`                                                | -              | Selected date range string in `format` (controlled mode)                                                             |
+| `defaultValue`    | `string`                                                | `''`           | Initial date range string (uncontrolled mode)                                                                        |
+| `onChange`        | `(event: { target: { name?, value: string } }) => void` | -              | Callback when the date range changes                                                                                 |
+| `format`          | `string`                                                | `'YYYY/MM/DD'` | Format of the `value` and `onChange` value                                                                           |
+| `displayFormat`   | `string`                                                | `'YYYY/MM/DD'` | 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 date (in `format`)                                                                                |
+| `maxDate`         | `string`                                                | -              | Maximum selectable date (in `format`)                                                                                |
+| `disableFuture`   | `boolean`                                               | `false`        | Disables all future dates                                                                                            |
+| `disablePast`     | `boolean`                                               | `false`        | Disables all past dates                                                                                              |
+| `inputReadOnly`   | `boolean`                                               | `false`        | Prevents keyboard typing (calendar-only input)                                                                       |
+| `hideClearButton` | `boolean`                                               | `false`        | Hides the clear button in the calendar popup                                                                         |
+
+### Alphabetic Month Tokens (MMM / MMMM)
+
+The `displayFormat` prop supports alphabetic month tokens for more human-readable date 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 dates through the calendar popup. Use the `locale` prop to control the language of month names.
+
+```tsx
+<DateRangePicker displayFormat="MMM DD, YYYY" locale="en-US" />
+// → "Apr 01, 2026 - Apr 09, 2026"
+```
+
+> **Note**: DateRangePicker also accepts all Input props (e.g., `size`, `variant`, `color`, `sx`).
+
 ## Accessibility
 
 - The input has `role="textbox"` and the calendar button has `aria-label="Toggle Calendar"` for screen reader identification.

package/dist/components/inputs/FilterableCheckboxGroup.md

@@ -6,10 +6,10 @@ FilterableCheckboxGroup is a multi-select component that combines a search input
 
 Key capabilities include a "Select all" toggle for bulk selection, automatic sorting (selected items first, then alphabetical), customizable list height, and built-in form integration via `label`, `helperText`, and `required` props. The component accepts options as either simple strings or `{ value, label }` objects.
 
-> **Form 구성 시 내장 prop 사용을 권장합니다**
+> **Using built-in props is recommended when building forms**
 >
-> 이 컴포넌트는 `label`, `helperText` 등의 Form 요소를 자체적으로 지원합니다.
-> Form을 구성할 때 Typography로 별도의 label이나 helperText를 만드는 대신, 컴포넌트의 내장 prop을 사용하세요.
+> This component provides built-in form-related props such as `label` and `helperText`.
+> When building a form, use the component's built-in props instead of creating separate labels or helper text with Typography.
 
 ```tsx
 <FilterableCheckboxGroup
@@ -310,6 +310,23 @@ When dealing with a large set of options like countries, the search filter and v
 
 5. **Keep option labels concise.** Long labels will be truncated with an ellipsis. If detailed descriptions are needed, consider using a tooltip or a separate detail view.
 
+## Props and Customization
+
+### Key Props
+
+| Prop          | Type                                                     | Default    | Description                                         |
+| ------------- | -------------------------------------------------------- | ---------- | --------------------------------------------------- |
+| `options`     | `{ value: string; label: string; disabled?: boolean }[]` | (required) | Array of checkbox options                           |
+| `value`       | `string[]`                                               | -          | Selected values (controlled mode)                   |
+| `onChange`    | `(value: string[]) => void`                              | -          | Callback when selection changes                     |
+| `label`       | `ReactNode`                                              | -          | Group label displayed above the component           |
+| `helperText`  | `ReactNode`                                              | -          | Helper text displayed below the component           |
+| `placeholder` | `string`                                                 | -          | Placeholder text for the search input               |
+| `required`    | `boolean`                                                | `false`    | Marks the field as required                         |
+| `disabled`    | `boolean`                                                | `false`    | Disables all checkboxes                             |
+| `size`        | `'sm' \| 'md' \| 'lg'`                                   | `'md'`     | Component size                                      |
+| `maxHeight`   | `string \| number`                                       | `300`      | Maximum height of the options list before scrolling |
+
 ## Accessibility
 
 - The search input is labeled by the component's `label` prop, ensuring screen readers announce its purpose.

package/dist/components/inputs/FormControl.md

@@ -294,8 +294,8 @@ function SettingsForm() {
 
 > **Tip: Use built-in form props instead**
 >
-> Input, Select, Textarea, DatePicker 등 Input 계열 컴포넌트는 `label`, `helperText` prop을 자체적으로 지원합니다.
-> 간단한 form 필드에는 각 컴포넌트의 내장 prop을 사용하는 것이 더 간결합니다.
+> Input-family components such as Input, Select, Textarea, and DatePicker support `label` and `helperText` props directly.
+> For simple form fields, using each component's built-in props is more concise.
 >
 > ```tsx
 > // ✅ Simpler: built-in props
@@ -352,6 +352,36 @@ function SettingsForm() {
 
 5. **Provide helpful error messages**: When using the error state, always include a FormHelperText explaining what went wrong and how to fix it.
 
+## Props and Customization
+
+### FormControl Props
+
+| Prop          | Type                                                           | Default      | Description                                                       |
+| ------------- | -------------------------------------------------------------- | ------------ | ----------------------------------------------------------------- |
+| `children`    | `ReactNode`                                                    | -            | Form field elements (FormLabel, Input, FormHelperText, etc.)      |
+| `error`       | `boolean`                                                      | `false`      | Applies error styling to child components                         |
+| `disabled`    | `boolean`                                                      | `false`      | Disables all child form elements                                  |
+| `required`    | `boolean`                                                      | `false`      | Adds required indicator to FormLabel and `aria-required` to input |
+| `size`        | `'sm' \| 'md' \| 'lg'`                                         | `'md'`       | Size applied to child components                                  |
+| `color`       | `'primary' \| 'neutral' \| 'danger' \| 'success' \| 'warning'` | `'neutral'`  | Color scheme                                                      |
+| `orientation` | `'horizontal' \| 'vertical'`                                   | `'vertical'` | Layout direction                                                  |
+| `sx`          | `SxProps`                                                      | -            | Custom styles using the MUI system                                |
+
+### FormLabel Props
+
+| Prop       | Type        | Default | Description                                             |
+| ---------- | ----------- | ------- | ------------------------------------------------------- |
+| `children` | `ReactNode` | -       | Label text                                              |
+| `required` | `boolean`   | -       | Shows asterisk (inherited from FormControl when nested) |
+
+### FormHelperText Props
+
+| Prop       | Type        | Default | Description                  |
+| ---------- | ----------- | ------- | ---------------------------- |
+| `children` | `ReactNode` | -       | Helper or error message text |
+
+> **Note**: FormControl, FormLabel, and FormHelperText accept all their respective Joy UI props.
+
 ## Accessibility
 
 - FormControl automatically associates FormLabel with the input using `htmlFor` and `id`.

package/dist/components/inputs/IconButton.md

@@ -402,6 +402,24 @@ import ArrowBackIcon from '@mui/icons-material/ArrowBack';
 
 5. **Maintain consistent sizing within the same context.** Use the same `size` and `variant` for all IconButtons in a toolbar or action group to keep the interface clean and predictable.
 
+## Props and Customization
+
+### Key Props
+
+| Prop        | Type                                                           | Default     | Description                              |
+| ----------- | -------------------------------------------------------------- | ----------- | ---------------------------------------- |
+| `children`  | `ReactNode`                                                    | -           | Icon element to render inside the button |
+| `variant`   | `'solid' \| 'soft' \| 'outlined' \| 'plain'`                   | `'plain'`   | Visual style                             |
+| `size`      | `'sm' \| 'md' \| 'lg'`                                         | `'md'`      | Button size                              |
+| `color`     | `'primary' \| 'neutral' \| 'danger' \| 'success' \| 'warning'` | `'neutral'` | Color scheme                             |
+| `disabled`  | `boolean`                                                      | `false`     | Disables the button                      |
+| `loading`   | `boolean`                                                      | `false`     | Shows a loading indicator                |
+| `component` | `ElementType`                                                  | `'button'`  | Root element type (polymorphic)          |
+| `onClick`   | `(event: MouseEvent) => void`                                  | -           | Click event handler                      |
+| `sx`        | `SxProps`                                                      | -           | Custom styles using the MUI system       |
+
+> **Note**: IconButton also accepts all Joy UI IconButton props and Framer Motion props.
+
 ## Accessibility
 
 - **`aria-label` is essential**: Every IconButton must have either an `aria-label`, `aria-labelledby`, or a wrapping Tooltip with `title` to provide a text alternative for screen readers.