@ceed/ads 1.29.1 → 1.30.1

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

@@ -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/ads';
+
+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.
@@ -299,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() {
@@ -334,7 +380,7 @@ function BookingForm() {
 }
 ```
 
-### Custom Date Disabling (Weekdays Only)
+## Custom Date Disabling (Weekdays Only)
 
 ```tsx
 function AppointmentPicker() {
@@ -358,7 +404,7 @@ function AppointmentPicker() {
 }
 ```
 
-### Locale-Aware Display
+## Locale-Aware Display
 
 ```tsx
 function RegionalDateField({ locale }: { locale: string }) {
@@ -432,6 +478,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/ads';
+
+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`.
@@ -367,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() {
@@ -403,7 +463,7 @@ function BookingForm() {
 }
 ```
 
-### Report Date Filter
+## Report Date Filter
 
 ```tsx
 function ReportFilters({ onFilter }) {
@@ -431,7 +491,7 @@ function ReportFilters({ onFilter }) {
 }
 ```
 
-### Separate API and Display Formats
+## Separate API and Display Formats
 
 ```tsx
 function DataExport() {
@@ -500,6 +560,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/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.