@ceed/ads 1.35.1 → 1.37.0-next.1

package/dist/components/inputs/DateRangePicker.md

@@ -56,13 +56,7 @@ import { DateRangePicker } from '@ceed/ads';
 function DateRangeForm() {
   const [dateRange, setDateRange] = useState('');
 
-  return (
-    <DateRangePicker
-      label="Select Date Range"
-      value={dateRange}
-      onChange={(e) => setDateRange(e.target.value)}
-    />
-  );
+  return <DateRangePicker label="Select Date Range" value={dateRange} onChange={(e) => setDateRange(e.target.value)} />;
 }
 ```
 
@@ -72,10 +66,10 @@ DateRangePicker supports three sizes (`sm`, `md`, `lg`) to fit different layouts
 
 ```tsx
 <Stack gap={2}>
-  <DateRangePicker size="sm" />
-  <DateRangePicker size="md" />
-  <DateRangePicker size="lg" />
-</Stack>
+    <DateRangePicker size="sm" />
+    <DateRangePicker size="md" />
+    <DateRangePicker size="lg" />
+  </Stack>
 ```
 
 ## Form Features
@@ -183,25 +177,31 @@ In controlled mode, the parent component manages the date range state via `value
 
 ```tsx
 <Stack gap={2}>
-  <DateRangePicker {...args} onChange={e => {
-    args.onChange?.(e);
-    setValue(e.target.value);
-  }} value={value} />
-  <Button onClick={() => {
-    const [start, end] = value.split(' - ');
-    function shiftMonth(dateString: string) {
-      const currentValue = new Date(dateString);
-      currentValue.setMonth(currentValue.getMonth() + 1);
-      const year = currentValue.getFullYear();
-      const month = String(currentValue.getMonth() + 1).padStart(2, '0');
-      const day = String(currentValue.getDate()).padStart(2, '0');
-      return `${year}/${month}/${day}`;
-    }
-    setValue(`${shiftMonth(start)} - ${shiftMonth(end)}`);
-  }}>
-  Shift Month
-</Button>
-</Stack>
+    <DateRangePicker
+      {...args}
+      onChange={(e) => {
+        args.onChange?.(e);
+        setValue(e.target.value);
+      }}
+      value={value}
+    />
+    <Button
+      onClick={() => {
+        const [start, end] = value.split(" - ");
+        function shiftMonth(dateString: string) {
+          const currentValue = new Date(dateString);
+          currentValue.setMonth(currentValue.getMonth() + 1);
+          const year = currentValue.getFullYear();
+          const month = String(currentValue.getMonth() + 1).padStart(2, "0");
+          const day = String(currentValue.getDate()).padStart(2, "0");
+          return `${year}/${month}/${day}`;
+        }
+        setValue(`${shiftMonth(start)} - ${shiftMonth(end)}`);
+      }}
+    >
+      Shift Month
+    </Button>
+  </Stack>
 ```
 
 ### Uncontrolled
@@ -225,31 +225,73 @@ The `format` prop controls the format of the value returned in `onChange`. The i
 
 ```tsx
 <Stack gap={2}>
-  <DateRangePicker {...args} value={value1} label="YYYY.MM.DD" name="YYYY.MM.DD" format="YYYY.MM.DD" onChange={e => {
-    setValue1(e.target.value);
-    args.onChange?.(e);
-  }} />
-  <DateRangePicker {...args} value={value2} label="YYYY/MM/DD" name="YYYY/MM/DD" format="YYYY/MM/DD" onChange={e => {
-    setValue2(e.target.value);
-    args.onChange?.(e);
-  }} />
-  <DateRangePicker {...args} value={value3} label="MM/DD/YYYY" name="MM/DD/YYYY" format="MM/DD/YYYY" onChange={e => {
-    setValue3(e.target.value);
-    args.onChange?.(e);
-  }} />
-  <DateRangePicker {...args} value={value4} label="YYYY-MM-DD" name="YYYY-MM-DD" format="YYYY-MM-DD" onChange={e => {
-    setValue4(e.target.value);
-    args.onChange?.(e);
-  }} />
-  <DateRangePicker {...args} value={value5} label="DD/MM/YYYY" name="DD/MM/YYYY" format="DD/MM/YYYY" onChange={e => {
-    setValue5(e.target.value);
-    args.onChange?.(e);
-  }} />
-  <DateRangePicker {...args} value={value6} label="DD.MM.YYYY" name="DD.MM.YYYY" format="DD.MM.YYYY" onChange={e => {
-    setValue6(e.target.value);
-    args.onChange?.(e);
-  }} />
-</Stack>
+    <DateRangePicker
+      {...args}
+      value={value1}
+      label="YYYY.MM.DD"
+      name="YYYY.MM.DD"
+      format="YYYY.MM.DD"
+      onChange={(e) => {
+        setValue1(e.target.value);
+        args.onChange?.(e);
+      }}
+    />
+    <DateRangePicker
+      {...args}
+      value={value2}
+      label="YYYY/MM/DD"
+      name="YYYY/MM/DD"
+      format="YYYY/MM/DD"
+      onChange={(e) => {
+        setValue2(e.target.value);
+        args.onChange?.(e);
+      }}
+    />
+    <DateRangePicker
+      {...args}
+      value={value3}
+      label="MM/DD/YYYY"
+      name="MM/DD/YYYY"
+      format="MM/DD/YYYY"
+      onChange={(e) => {
+        setValue3(e.target.value);
+        args.onChange?.(e);
+      }}
+    />
+    <DateRangePicker
+      {...args}
+      value={value4}
+      label="YYYY-MM-DD"
+      name="YYYY-MM-DD"
+      format="YYYY-MM-DD"
+      onChange={(e) => {
+        setValue4(e.target.value);
+        args.onChange?.(e);
+      }}
+    />
+    <DateRangePicker
+      {...args}
+      value={value5}
+      label="DD/MM/YYYY"
+      name="DD/MM/YYYY"
+      format="DD/MM/YYYY"
+      onChange={(e) => {
+        setValue5(e.target.value);
+        args.onChange?.(e);
+      }}
+    />
+    <DateRangePicker
+      {...args}
+      value={value6}
+      label="DD.MM.YYYY"
+      name="DD.MM.YYYY"
+      format="DD.MM.YYYY"
+      onChange={(e) => {
+        setValue6(e.target.value);
+        args.onChange?.(e);
+      }}
+    />
+  </Stack>
 ```
 
 ### Display Format (`displayFormat`)
@@ -258,31 +300,73 @@ The `displayFormat` prop controls what the user sees in the input field. This is
 
 ```tsx
 <Stack gap={2}>
-  <DateRangePicker {...args} value={value1} label="YYYY.MM.DD" name="YYYY.MM.DD" displayFormat="YYYY.MM.DD" onChange={e => {
-    setValue1(e.target.value);
-    args.onChange?.(e);
-  }} />
-  <DateRangePicker {...args} value={value2} label="YYYY/MM/DD" name="YYYY/MM/DD" displayFormat="YYYY/MM/DD" onChange={e => {
-    setValue2(e.target.value);
-    args.onChange?.(e);
-  }} />
-  <DateRangePicker {...args} value={value3} label="MM/DD/YYYY" name="MM/DD/YYYY" displayFormat="MM/DD/YYYY" onChange={e => {
-    setValue3(e.target.value);
-    args.onChange?.(e);
-  }} />
-  <DateRangePicker {...args} value={value4} label="YYYY-MM-DD" name="YYYY-MM-DD" displayFormat="YYYY-MM-DD" onChange={e => {
-    setValue4(e.target.value);
-    args.onChange?.(e);
-  }} />
-  <DateRangePicker {...args} value={value5} label="DD/MM/YYYY" name="DD/MM/YYYY" displayFormat="DD/MM/YYYY" onChange={e => {
-    setValue5(e.target.value);
-    args.onChange?.(e);
-  }} />
-  <DateRangePicker {...args} value={value6} label="DD.MM.YYYY" name="DD.MM.YYYY" displayFormat="DD.MM.YYYY" onChange={e => {
-    setValue6(e.target.value);
-    args.onChange?.(e);
-  }} />
-</Stack>
+    <DateRangePicker
+      {...args}
+      value={value1}
+      label="YYYY.MM.DD"
+      name="YYYY.MM.DD"
+      displayFormat="YYYY.MM.DD"
+      onChange={(e) => {
+        setValue1(e.target.value);
+        args.onChange?.(e);
+      }}
+    />
+    <DateRangePicker
+      {...args}
+      value={value2}
+      label="YYYY/MM/DD"
+      name="YYYY/MM/DD"
+      displayFormat="YYYY/MM/DD"
+      onChange={(e) => {
+        setValue2(e.target.value);
+        args.onChange?.(e);
+      }}
+    />
+    <DateRangePicker
+      {...args}
+      value={value3}
+      label="MM/DD/YYYY"
+      name="MM/DD/YYYY"
+      displayFormat="MM/DD/YYYY"
+      onChange={(e) => {
+        setValue3(e.target.value);
+        args.onChange?.(e);
+      }}
+    />
+    <DateRangePicker
+      {...args}
+      value={value4}
+      label="YYYY-MM-DD"
+      name="YYYY-MM-DD"
+      displayFormat="YYYY-MM-DD"
+      onChange={(e) => {
+        setValue4(e.target.value);
+        args.onChange?.(e);
+      }}
+    />
+    <DateRangePicker
+      {...args}
+      value={value5}
+      label="DD/MM/YYYY"
+      name="DD/MM/YYYY"
+      displayFormat="DD/MM/YYYY"
+      onChange={(e) => {
+        setValue5(e.target.value);
+        args.onChange?.(e);
+      }}
+    />
+    <DateRangePicker
+      {...args}
+      value={value6}
+      label="DD.MM.YYYY"
+      name="DD.MM.YYYY"
+      displayFormat="DD.MM.YYYY"
+      onChange={(e) => {
+        setValue6(e.target.value);
+        args.onChange?.(e);
+      }}
+    />
+  </Stack>
 ```
 
 **Supported format tokens:**
@@ -296,8 +380,8 @@ The `displayFormat` prop controls what the user sees in the input field. This is
 ```tsx
 // format affects onChange value; displayFormat affects what users see
 <DateRangePicker
-  format="YYYY-MM-DD"        // onChange returns "2024-04-01 - 2024-04-15"
-  displayFormat="MM/DD/YYYY"  // Input shows "04/01/2024 - 04/15/2024"
+  format="YYYY-MM-DD" // onChange returns "2024-04-01 - 2024-04-15"
+  displayFormat="MM/DD/YYYY" // Input shows "04/01/2024 - 04/15/2024"
 />
 ```
 
@@ -353,25 +437,37 @@ Use the `numberOfMonths` prop to display two calendar months side by side in the
 When combined with `presets`, the dual calendar provides a fast, at-a-glance interface for report and analytics date filters.
 
 ```tsx
-<DateRangePicker {...args} value={value} onChange={e => {
-  setValue(e.target.value);
-  args.onChange?.(e);
-}} disableFuture presets={[{
-  label: 'Today',
-  value: `${fmt(today)} - ${fmt(today)}`
-}, {
-  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')
-}]} />
+<DateRangePicker
+    {...args}
+    value={value}
+    onChange={(e) => {
+      setValue(e.target.value);
+      args.onChange?.(e);
+    }}
+    disableFuture
+    presets={[
+      {
+        label: "Today",
+        value: `${fmt(today)} - ${fmt(today)}`
+      },
+      {
+        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
@@ -394,28 +490,40 @@ Use the `presets` prop to display quick-select options alongside the calendar, s
 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')
-}]} />
+<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
@@ -466,15 +574,21 @@ Remove the clear button from the calendar popup using `hideClearButton`.
 Example of integrating an external reset button to clear the selected date range programmatically.
 
 ```tsx
-<div style={{
-  display: 'flex',
-  gap: '10px'
-}}>
-<DateRangePicker {...props} value={value} onChange={event => {
-  setValue(event.target.value);
-}} />
-<Button onClick={() => setValue('')}>Reset</Button>
-</div>
+<div
+    style={{
+      display: "flex",
+      gap: "10px"
+    }}
+  >
+    <DateRangePicker
+      {...props}
+      value={value}
+      onChange={(event) => {
+        setValue(event.target.value);
+      }}
+    />
+    <Button onClick={() => setValue("")}>Reset</Button>
+  </div>
 ```
 
 ## Booking Form
@@ -575,10 +689,7 @@ function DataExport() {
 
 ```tsx
 // Store ISO format, display locale format
-<DateRangePicker
-  format="YYYY-MM-DD"
-  displayFormat="MM/DD/YYYY"
-/>
+<DateRangePicker format="YYYY-MM-DD" displayFormat="MM/DD/YYYY" />
 ```
 
 3. **Use `inputReadOnly` on mobile**: On touch devices, keyboard input for date ranges is error-prone. Use `inputReadOnly` to force calendar selection.
@@ -605,7 +716,7 @@ const getDuration = (value) => {
   return `${days} day${days !== 1 ? 's' : ''} selected`;
 };
 
-<DateRangePicker helperText={getDuration(dateRange)} />
+<DateRangePicker helperText={getDuration(dateRange)} />;
 ```
 
 ## Props and Customization

package/dist/components/inputs/FilterMenu.md

@@ -7,10 +7,14 @@ FilterMenu is a comprehensive filtering component that supports multiple filter
 FilterMenu is ideal for data-heavy admin interfaces such as tables, lists, and dashboards where users need to narrow down results based on multiple criteria. It supports both controlled and uncontrolled state management, allowing flexible integration with different state architectures.
 
 ```tsx
-<FilterMenu {...args} defaultValues={values} onChange={newValues => {
-  setValues(newValues);
-  args.onChange!(newValues);
-}} />
+<FilterMenu
+    {...args}
+    defaultValues={values}
+    onChange={(newValues) => {
+      setValues(newValues);
+      args.onChange!(newValues);
+    }}
+  />
 ```
 
 | Field                        | Description | Default |
@@ -128,6 +132,21 @@ A date range picker filter. The value is stored as a two-element array of date s
 }
 ```
 
+### Month Range
+
+A month range picker filter, built on `MonthRangePicker`. The value is stored as a two-element array of month strings. Both ends follow the `format` you provide (default `YYYY/MM`), so the value tuple format is fully controlled by the consumer.
+
+```tsx
+{
+  id: 'monthRange',
+  type: 'month-range',
+  label: 'Month Range',
+  format: 'YYYY-MM',
+  displayFormat: 'MMM YYYY',
+}
+// value → ['2025-01', '2025-06']
+```
+
 ### Currency Input
 
 A single currency value input field.
@@ -204,10 +223,14 @@ A searchable single-select filter with autocomplete support.
 In controlled mode, you manage the filter state externally using `values` (or `defaultValues` with an `onChange` handler).
 
 ```tsx
-<FilterMenu {...args} defaultValues={values} onChange={newValues => {
-  setValues(newValues);
-  args.onChange!(newValues);
-}} />
+<FilterMenu
+    {...args}
+    defaultValues={values}
+    onChange={(newValues) => {
+      setValues(newValues);
+      args.onChange!(newValues);
+    }}
+  />
 ```
 
 ## Uncontrolled FilterMenu
@@ -218,6 +241,111 @@ In uncontrolled mode, FilterMenu manages its own internal state. This is useful
 <FilterMenu />
 ```
 
+## Filter Button with Dropdown Trigger
+
+In real applications, FilterMenu is opened from a toolbar "Filter" button rather than rendered inline. Compose it with `Dropdown` and `MenuButtonTrigger`: FilterMenu renders with `position: relative` (it is not a centered modal), so it sits naturally inside the dropdown popover. Control the `Dropdown` `open` state so the panel's **Apply** / **Reset** buttons can close the popover through `onClose`.
+
+```tsx
+<Dropdown open={open} onOpenChange={(_event, isOpen) => setOpen(isOpen)}>
+    <MenuButtonTrigger
+      variant="outlined"
+      startDecorator={<FilterListIcon />}
+      endDecorator={<ExpandMoreIcon />}
+    >
+      Filters
+    </MenuButtonTrigger>
+    <Menu
+      placement="bottom-start"
+      sx={{
+        p: 0,
+        border: "none",
+        boxShadow: "none",
+        bgcolor: "transparent"
+      }}
+    >
+      <FilterMenu
+        filters={[
+          {
+            id: "status",
+            type: "checkbox-group",
+            label: "Status",
+            options: [
+              {
+                label: "Active",
+                value: "active"
+              },
+              {
+                label: "Inactive",
+                value: "inactive"
+              }
+            ]
+          },
+          {
+            id: "priority",
+            type: "radio-group",
+            label: "Priority",
+            options: [
+              {
+                label: "High",
+                value: "high"
+              },
+              {
+                label: "Medium",
+                value: "medium"
+              },
+              {
+                label: "Low",
+                value: "low"
+              }
+            ]
+          },
+          {
+            id: "amountRange",
+            type: "currency-range",
+            label: "Amount Range",
+            currency: "USD"
+          },
+          {
+            id: "monthRange",
+            type: "month-range",
+            label: "Month Range",
+            format: "YYYY-MM",
+            displayFormat: "MMM YYYY"
+          }
+        ]}
+        values={values}
+        onChange={(newValues) => setValues(newValues)}
+        onClose={() => setOpen(false)}
+        useReset
+      />
+    </Menu>
+  </Dropdown>
+```
+
+```tsx
+import { Dropdown, MenuButtonTrigger, Menu, FilterMenu } from '@ceed/ads';
+import FilterListIcon from '@mui/icons-material/FilterList';
+import ExpandMoreIcon from '@mui/icons-material/ExpandMore';
+
+function ToolbarFilter() {
+  const [open, setOpen] = useState(false);
+  const [values, setValues] = useState({ status: ['active'] });
+
+  return (
+    <Dropdown open={open} onOpenChange={(_event, isOpen) => setOpen(isOpen)}>
+      <MenuButtonTrigger variant="outlined" startDecorator={<FilterListIcon />} endDecorator={<ExpandMoreIcon />}>
+        Filters
+      </MenuButtonTrigger>
+      <Menu placement="bottom-start" sx={{ p: 0, border: 'none', boxShadow: 'none', bgcolor: 'transparent' }}>
+        <FilterMenu filters={filters} values={values} onChange={setValues} onClose={() => setOpen(false)} useReset />
+      </Menu>
+    </Dropdown>
+  );
+}
+```
+
+> **Note**: Use `MenuButtonTrigger` (the low-level composition trigger), not the high-level `MenuButton` -- the latter renders its own item list and cannot host a FilterMenu. Strip the `Menu` surface styling (`p: 0`, transparent background, no border/shadow) so only FilterMenu's own panel surface is visible inside the popover. When FilterMenu is mounted inside `Dropdown`, the dropdown automatically keeps itself open while a picker filter's calendar (e.g. `date-range`, `month-range`) takes focus, so the panel survives nested popover interaction without any custom `onOpenChange` handling.
+
 ## Table Filters
 
 ```tsx
@@ -393,6 +521,7 @@ type FilterItem =
   | FilterableCheckboxGroupItem
   | FilterRadioGroupItem
   | FilterDateRangeItem
+  | FilterMonthRangeItem
   | FilterCurrencyInputItem
   | FilterCurrencyRangeItem
   | FilterPercentageInputItem
@@ -408,6 +537,7 @@ type FilterItem =
 | `'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` |
+| `'month-range'`               | `[string, string]`     | Month range picker. Supports `format`, `displayFormat`, `locale`, `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`                                      |