@ceed/ads 1.30.0 → 1.31.0

package/dist/components/inputs/CurrencyInput.md

@@ -172,9 +172,7 @@ When `useMinorUnit` is true, the component converts between display values and m
 <CurrencyInput currency="KRW" useMinorUnit value={10000} />
 ```
 
-## Common Use Cases
-
-### Product Price Editor
+## Product Price Editor
 
 ```tsx
 function ProductPriceEditor() {
@@ -202,7 +200,7 @@ function ProductPriceEditor() {
 }
 ```
 
-### Invoice Line Item
+## Invoice Line Item
 
 ```tsx
 function InvoiceLineItem({ item, onChange }) {
@@ -221,7 +219,7 @@ function InvoiceLineItem({ item, onChange }) {
 }
 ```
 
-### Budget Limit Input
+## Budget Limit Input
 
 ```tsx
 function BudgetSetting() {
@@ -261,6 +259,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/FilterMenu.md

@@ -199,9 +199,7 @@ A searchable single-select filter with autocomplete support.
 }
 ```
 
-## Examples
-
-### Controlled Mode
+## Controlled FilterMenu
 
 In controlled mode, you manage the filter state externally using `values` (or `defaultValues` with an `onChange` handler).
 
@@ -212,7 +210,7 @@ In controlled mode, you manage the filter state externally using `values` (or `d
 }} />
 ```
 
-### Uncontrolled Mode
+## Uncontrolled FilterMenu
 
 In uncontrolled mode, FilterMenu manages its own internal state. This is useful when you only need the final filter values on submission.
 
@@ -220,9 +218,7 @@ In uncontrolled mode, FilterMenu manages its own internal state. This is useful
 <FilterMenu />
 ```
 
-## Common Use Cases
-
-### Table Filters
+## Table Filters
 
 ```tsx
 function DataTable() {
@@ -266,7 +262,7 @@ function DataTable() {
 }
 ```
 
-### Dashboard Filters
+## Dashboard Filters
 
 ```tsx
 function DashboardFilters({ onFilterChange }) {
@@ -300,7 +296,7 @@ function DashboardFilters({ onFilterChange }) {
 }
 ```
 
-### Invoice Filters
+## Invoice Filters
 
 ```tsx
 function InvoiceFilters({ onFilterChange }) {
@@ -372,6 +368,86 @@ filters={[
 
 5. **Prefer controlled mode for complex state**: When filter values need to be synced with URL parameters, API requests, or other UI elements, use the controlled pattern with `values` and `onChange`.
 
+## Props and Customization
+
+### FilterMenu Props
+
+| Prop            | Type                                    | Default | Description                                            |
+| --------------- | --------------------------------------- | ------- | ------------------------------------------------------ |
+| `filters`       | `FilterItem[]`                          | `[]`    | Array of filter item configurations                    |
+| `values`        | `Record<string, any>`                   | -       | Controlled filter values (keyed by filter `id`)        |
+| `defaultValues` | `Record<string, any>`                   | -       | Initial filter values for uncontrolled mode            |
+| `resetValues`   | `Record<string, any>`                   | `{}`    | Values applied when Reset/Clear button is clicked      |
+| `onChange`      | `(values: Record<string, any>) => void` | -       | Callback when Apply button is clicked                  |
+| `onClose`       | `() => void`                            | -       | Callback when the filter panel closes                  |
+| `useReset`      | `boolean`                               | `false` | Show a Reset button (requires 2+ filters)              |
+| `useClear`      | `boolean`                               | `false` | Show a Clear button (for single-filter scenarios only) |
+
+### FilterItem Union Type
+
+All filter items share a base shape with `id`, `label`, `hidden`, `value`, and `onChange`. The `type` field determines the specific filter UI:
+
+```tsx
+type FilterItem =
+  | FilterCheckboxGroupItem
+  | FilterableCheckboxGroupItem
+  | FilterRadioGroupItem
+  | FilterDateRangeItem
+  | FilterCurrencyInputItem
+  | FilterCurrencyRangeItem
+  | FilterPercentageInputItem
+  | FilterPercentageRangeItem
+  | FilterAutocompleteItem;
+```
+
+### Filter Item Types Reference
+
+| Type                          | Value Type             | Description                                                                                                                           |
+| ----------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `'checkbox-group'`            | `(string \| number)[]` | Multi-select with checkboxes                                                                                                          |
+| `'filterable-checkbox-group'` | `string[]`             | Searchable multi-select with checkboxes. Supports `placeholder` and `maxHeight`                                                       |
+| `'radio-group'`               | `string \| number`     | Single-select with radio buttons                                                                                                      |
+| `'date-range'`                | `[string, string]`     | Date range picker. Supports `displayFormat`, `inputReadOnly`, `hideClearButton`, `minDate`, `maxDate`, `disableFuture`, `disablePast` |
+| `'currency-input'`            | `number`               | Single currency value. Supports `currency`, `useMinorUnit`, `max`, `placeholder`                                                      |
+| `'currency-range'`            | `[number, number]`     | Currency range (min/max). Supports same props as currency-input                                                                       |
+| `'percentage-input'`          | `number`               | Single percentage value. Supports `useMinorUnit`, `maxDecimalScale`, `min`, `max`, `placeholder`                                      |
+| `'percentage-range'`          | `[number, number]`     | Percentage range (min/max). Supports same props as percentage-input                                                                   |
+| `'autocomplete'`              | `string \| number`     | Searchable single-select. Supports `options`, `multiple`, `placeholder`                                                               |
+
+### Filter Item Common Props
+
+| Prop       | Type              | Default    | Description                                                |
+| ---------- | ----------------- | ---------- | ---------------------------------------------------------- |
+| `id`       | `string`          | (required) | Unique identifier — used as the key in values/onChange     |
+| `label`    | `string`          | (required) | Display label for the filter section                       |
+| `hidden`   | `boolean`         | `false`    | Hide the filter without removing it from the configuration |
+| `value`    | varies by type    | -          | Controlled value for individual filter                     |
+| `onChange` | `(value) => void` | -          | Individual change handler (only in controlled mode)        |
+
+### Complete Filter Item Examples
+
+```tsx
+// checkbox-group
+{ id: 'status', type: 'checkbox-group', label: 'Status',
+  options: [{ label: 'Active', value: 'active' }, { label: 'Inactive', value: 'inactive' }] }
+
+// filterable-checkbox-group with maxHeight
+{ id: 'categories', type: 'filterable-checkbox-group', label: 'Categories',
+  options: categories, placeholder: 'Search...', maxHeight: 200 }
+
+// date-range with display format
+{ id: 'dateRange', type: 'date-range', label: 'Date Range',
+  displayFormat: 'MM/DD/YYYY', inputReadOnly: true }
+
+// currency-range with minor units
+{ id: 'amount', type: 'currency-range', label: 'Amount',
+  currency: 'USD', useMinorUnit: true }
+
+// autocomplete
+{ id: 'category', type: 'autocomplete', label: 'Category',
+  options: ['Cat 1', 'Cat 2', 'Cat 3'], placeholder: 'Select...' }
+```
+
 ## Accessibility
 
 - Each filter section is labeled with its `label` prop, providing clear context for screen readers.

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
@@ -224,9 +224,7 @@ The component supports both full and partial disabling.
 </Stack>
 ```
 
-## Common Use Cases
-
-### Filter Panel
+## Filter Panel
 
 Use FilterableCheckboxGroup in a sidebar or panel to let users filter a data table or list by multiple criteria.
 
@@ -254,7 +252,7 @@ function FilterPanel({ categories, onFilterChange }) {
 }
 ```
 
-### User Role Assignment
+## User Role Assignment
 
 Assign multiple roles to a user from a searchable list.
 
@@ -276,7 +274,7 @@ Assign multiple roles to a user from a searchable list.
 />
 ```
 
-### Region / Country Selection
+## Region / Country Selection
 
 When dealing with a large set of options like countries, the search filter and virtual scrolling work together for fast selection.
 
@@ -310,6 +308,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

@@ -224,9 +224,7 @@ FormHelperText provides supplementary guidance below the input. It automatically
 </FormControl>
 ```
 
-## Common Use Cases
-
-### Registration Form
+## Registration Form
 
 ```tsx
 function RegistrationForm() {
@@ -260,7 +258,7 @@ function RegistrationForm() {
 }
 ```
 
-### Settings Form with Mixed Controls
+## Settings Form with Mixed Controls
 
 ```tsx
 function SettingsForm() {
@@ -294,8 +292,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 +350,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

@@ -294,9 +294,7 @@ A practical example of IconButton used for common CRUD operations with distinct
 </div>
 ```
 
-## Common Use Cases
-
-### Table Row Actions
+## Table Row Actions
 
 ```tsx
 import { IconButton, Tooltip } from '@ceed/ads';
@@ -327,7 +325,7 @@ function RowActions({ onView, onEdit, onDelete }) {
 }
 ```
 
-### Dialog Close Button
+## Dialog Close Button
 
 ```tsx
 import CloseIcon from '@mui/icons-material/Close';
@@ -344,7 +342,7 @@ import CloseIcon from '@mui/icons-material/Close';
 </IconButton>
 ```
 
-### Navigation Back Button
+## Navigation Back Button
 
 ```tsx
 import ArrowBackIcon from '@mui/icons-material/ArrowBack';
@@ -402,6 +400,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.