@ceed/cds 1.28.1 → 1.29.1

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

@@ -256,6 +256,54 @@ Common patterns: `YYYY/MM/DD` (default), `YYYY-MM-DD` (ISO 8601), `MM/DD/YYYY` (
 
 ## Additional Features
 
+### Presets
+
+Use the `presets` prop to display a list of quick-select options alongside the calendar. This is useful when users frequently select common dates like "Today" or a specific day offset. The preset panel appears to the right of the calendar inside the popup.
+
+Each preset's `value` must match the component's `format` prop. When the current value matches a preset, that preset is automatically highlighted -- regardless of whether the value was set via the preset button or by selecting the same date on the calendar.
+
+```tsx
+<DatePicker {...args} value={value} onChange={e => {
+  setValue(e.target.value);
+  args.onChange?.(e);
+}} presets={[{
+  label: 'Today',
+  value: fmt(today)
+}, {
+  label: 'Yesterday',
+  value: daysAgo(1)
+}, {
+  label: '3 days ago',
+  value: daysAgo(3)
+}, {
+  label: '1 week ago',
+  value: daysAgo(7)
+}]} />
+```
+
+```tsx
+import { DatePicker } from '@ceed/cds';
+
+function QuickDateSelect() {
+  const [date, setDate] = useState('');
+  const today = new Date();
+  const fmt = (d: Date) =>
+    `${d.getFullYear()}/${String(d.getMonth() + 1).padStart(2, '0')}/${String(d.getDate()).padStart(2, '0')}`;
+
+  return (
+    <DatePicker
+      label="Select Date"
+      value={date}
+      onChange={(e) => setDate(e.target.value)}
+      presets={[
+        { label: 'Today', value: fmt(today) },
+        { label: 'Yesterday', value: fmt(new Date(today.getTime() - 86400000)) },
+      ]}
+    />
+  );
+}
+```
+
 ### Reset Button
 
 Pair DatePicker with an external reset button to programmatically clear the value.
@@ -432,6 +480,42 @@ 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               |
+| `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.
+
+> **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

@@ -339,6 +339,68 @@ Fully read-only state where neither typing nor calendar selection is available.
 
 ## Additional Options
 
+### Presets
+
+Use the `presets` prop to display quick-select options alongside the calendar, such as "Last 7 days" or "Last 1 month". The preset panel appears to the right of the calendar inside the popup, providing one-click access to commonly used date ranges.
+
+Each preset's `value` must match the component's `format` prop and use the `-` separator (e.g., `"2026/03/01 - 2026/04/03"`). When the current value matches a preset, that preset is automatically highlighted -- regardless of whether the value was set via the preset button or by selecting the same range on the calendar.
+
+```tsx
+<DateRangePicker {...args} value={value} onChange={e => {
+  setValue(e.target.value);
+  args.onChange?.(e);
+}} presets={[{
+  label: 'Today',
+  value: `${fmt(today)} - ${fmt(today)}`
+}, {
+  label: 'Last 3 days',
+  value: range(3)
+}, {
+  label: 'Last 7 days',
+  value: range(7)
+}, {
+  label: 'Last 1 month',
+  value: range(1, 'months')
+}, {
+  label: 'Last 3 months',
+  value: range(3, 'months')
+}, {
+  label: 'Last 6 months',
+  value: range(6, 'months')
+}]} />
+```
+
+```tsx
+import { DateRangePicker } from '@ceed/cds';
+
+function ReportFilter() {
+  const [dateRange, setDateRange] = useState('');
+  const today = new Date();
+  const fmt = (d: Date) =>
+    `${d.getFullYear()}/${String(d.getMonth() + 1).padStart(2, '0')}/${String(d.getDate()).padStart(2, '0')}`;
+  const monthsAgo = (n: number) => {
+    const d = new Date(today);
+    d.setMonth(d.getMonth() - n);
+    return `${fmt(d)} - ${fmt(today)}`;
+  };
+
+  return (
+    <DateRangePicker
+      label="Report Period"
+      value={dateRange}
+      onChange={(e) => setDateRange(e.target.value)}
+      disableFuture
+      presets={[
+        { label: 'Last 7 days', value: `${fmt(new Date(today.getTime() - 7 * 86400000))} - ${fmt(today)}` },
+        { label: 'Last 1 month', value: monthsAgo(1) },
+        { label: 'Last 3 months', value: monthsAgo(3) },
+        { label: 'Last 6 months', value: monthsAgo(6) },
+      ]}
+    />
+  );
+}
+```
+
 ### Hide Clear Button
 
 Remove the clear button from the calendar popup using `hideClearButton`.
@@ -500,6 +562,32 @@ 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                      |
+| `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             |
+
+> **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.