@ceed/ads 1.29.1 → 1.30.0-next.1

package/dist/components/inputs/MonthRangePicker.md

@@ -2,9 +2,7 @@
 
 ## Introduction
 
-MonthRangePicker is a form input component that allows users to select a range of months (start month and end month) from a calendar popup. Unlike DateRangePicker which provides day-level granularity, MonthRangePicker focuses on month-level selection -- users click once to set the start month and again to set the end month.
-
-It is ideal for scenarios like fiscal period reporting, quarterly comparisons, subscription durations, or any use case requiring a span of months without specific day selection. The component supports multiple value formats, controlled and uncontrolled modes, and date range constraints.
+MonthRangePicker is a form input component that allows users to select a range of months (start month and end month) from a calendar popup. Unlike DateRangePicker which provides day-level granularity, MonthRangePicker focuses on month-level selection. It is ideal for scenarios like fiscal period reporting, quarterly comparisons, subscription duration, or any use case requiring a span of months without specific day selection.
 
 ```tsx
 <MonthRangePicker />
@@ -27,6 +25,15 @@ It is ideal for scenarios like fiscal period reporting, quarterly comparisons, s
 | format        | —           | —       |
 | onChange      | —           | —       |
 
+> ⚠️ **Usage Warning** ⚠️
+>
+> MonthRangePicker has unique formatting behaviors:
+>
+> - **Value format**: Values use `"YYYY/MM - YYYY/MM"` format (without day component)
+> - **Range validation**: Ensure start month is before or equal to end month
+> - **Format consistency**: Both months in the range must match the `format` prop
+> - **Month boundaries**: Consider inclusive vs exclusive range interpretations
+
 ## Usage
 
 ```tsx
@@ -45,14 +52,19 @@ function MonthRangeForm() {
 }
 ```
 
-> 💡 **Use built-in form props**
->
-> This component natively supports form elements such as `label` and `helperText` props.
-> When building forms, use these built-in props instead of manually composing labels and helper text with Typography.
+## Examples
 
-## Sizes
+### Playground
 
-MonthRangePicker supports three sizes (`sm`, `md`, `lg`) for different layouts and contexts.
+Interactive example with all controls.
+
+```tsx
+<MonthRangePicker />
+```
+
+### Sizes
+
+MonthRangePicker supports three sizes for different layouts.
 
 ```tsx
 <Stack gap={2}>
@@ -62,11 +74,9 @@ MonthRangePicker supports three sizes (`sm`, `md`, `lg`) for different layouts a
 </Stack>
 ```
 
-## Form Field Features
-
 ### With Label
 
-Add a label above the month range picker to indicate the field purpose.
+Add a label above the month range picker.
 
 ```tsx
 <MonthRangePicker label="Month Range" />
@@ -74,7 +84,7 @@ Add a label above the month range picker to indicate the field purpose.
 
 ### With Helper Text
 
-Provide additional guidance below the input to help users understand the expected selection.
+Provide additional guidance below the input.
 
 ```tsx
 <MonthRangePicker
@@ -83,43 +93,41 @@ Provide additional guidance below the input to help users understand the expecte
 />
 ```
 
-### Required Field
+### Error State
 
-Mark the field as required in forms. An asterisk indicator is displayed alongside the label.
+Show validation errors with error styling.
 
 ```tsx
 <MonthRangePicker
-  label="Label"
-  helperText="I'm helper text"
-  required
+  label="Month"
+  helperText="Please select a month"
+  error
 />
 ```
 
-### Error State
+### Required Field
 
-Display validation errors with error styling applied to the input, label, and helper text.
+Mark the field as required in forms.
 
 ```tsx
 <MonthRangePicker
-  label="Month"
-  helperText="Please select a month"
-  error
+  label="Label"
+  helperText="I'm helper text"
+  required
 />
 ```
 
 ### Disabled
 
-Prevent user interaction when the picker is disabled.
+Prevent user interaction when disabled.
 
 ```tsx
 <MonthRangePicker disabled />
 ```
 
-## Date Constraints
-
 ### Minimum Date
 
-Restrict selection to months on or after a minimum date. Months before the limit are visually disabled.
+Restrict selection to months on or after a minimum date.
 
 ```tsx
 <MonthRangePicker minDate="2024-04-10" />
@@ -127,7 +135,7 @@ Restrict selection to months on or after a minimum date. Months before the limit
 
 ### Maximum Date
 
-Restrict selection to months on or before a maximum date. Months after the limit are visually disabled.
+Restrict selection to months on or before a maximum date.
 
 ```tsx
 <MonthRangePicker maxDate="2024-04-10" />
@@ -135,7 +143,7 @@ Restrict selection to months on or before a maximum date. Months after the limit
 
 ### Disable Future
 
-Prevent selection of any month in the future, relative to the current date.
+Prevent selection of months in the future.
 
 ```tsx
 <MonthRangePicker disableFuture />
@@ -143,17 +151,15 @@ Prevent selection of any month in the future, relative to the current date.
 
 ### Disable Past
 
-Prevent selection of any month in the past, relative to the current date.
+Prevent selection of months in the past.
 
 ```tsx
 <MonthRangePicker disablePast />
 ```
 
-## Controlled vs Uncontrolled
-
 ### Controlled
 
-The parent component manages the month range state via the `value` and `onChange` props. External buttons or logic can programmatically update the selected range.
+Parent component manages the month range state.
 
 ```tsx
 <Stack gap={2}>
@@ -176,7 +182,7 @@ The parent component manages the month range state via the `value` and `onChange
 
 ### Uncontrolled
 
-The component manages its own state internally using `defaultValue`. The parent can still listen for changes via `onChange`.
+Component manages its own state internally.
 
 ```tsx
 <MonthRangePicker
@@ -186,11 +192,9 @@ The component manages its own state internally using `defaultValue`. The parent
 />
 ```
 
-## Formats
-
-The `format` prop determines both the display format and the value emitted by `onChange`. Unlike MonthPicker, MonthRangePicker does not have a separate `displayFormat` prop -- the `format` prop controls both.
+### With Formats
 
-The value is a string with start and end months separated by `-` (e.g., `"2024/04 - 2024/09"`).
+Different value formats for regional preferences.
 
 ```tsx
 <Stack gap={2}>
@@ -203,7 +207,7 @@ The value is a string with start and end months separated by `-` (e.g., `"2024/0
 
 ### With Reset Button
 
-A controlled example with an external reset button to clear the selected range.
+Example with an external reset button.
 
 ```tsx
 <div style={{
@@ -217,6 +221,25 @@ A controlled example with an external reset button to clear the selected range.
 </div>
 ```
 
+## When to Use
+
+### ✅ Good Use Cases
+
+- **Fiscal period reports**: Q1-Q4 reports, fiscal year ranges
+- **Subscription periods**: Multi-month subscription durations
+- **Budget planning**: Budget allocation across multiple months
+- **Historical comparisons**: Compare data across month spans
+- **Seasonal analysis**: Analyzing seasonal trends
+- **Project timelines**: Multi-month project duration
+
+### ❌ When Not to Use
+
+- **Single month selection**: Use MonthPicker instead
+- **Specific date ranges**: Use DateRangePicker when days matter
+- **Year selection**: Use a year picker or dropdown
+- **Quarter selection**: Consider custom quarter selector
+- **Indefinite periods**: Use separate start/end fields with "ongoing" option
+
 ## Common Use Cases
 
 ### Fiscal Period Report
@@ -248,13 +271,14 @@ function FiscalReportSelector() {
 }
 ```
 
-### Subscription Duration with Month Count
+### Subscription Duration
 
 ```tsx
 function SubscriptionForm() {
   const [duration, setDuration] = useState('');
 
-  const getMonthsCount = (value: string) => {
+  // Calculate months count
+  const getMonthsCount = (value) => {
     if (!value) return 0;
     const [start, end] = value.split(' - ');
     const [startYear, startMonth] = start.split('/').map(Number);
@@ -262,19 +286,65 @@ function SubscriptionForm() {
     return (endYear - startYear) * 12 + (endMonth - startMonth) + 1;
   };
 
+  const monthsCount = getMonthsCount(duration);
+
   return (
-    <MonthRangePicker
-      label="Subscription Period"
-      value={duration}
-      onChange={(e) => setDuration(e.target.value)}
-      disablePast
-      helperText={
-        getMonthsCount(duration) > 0
-          ? `${getMonthsCount(duration)} month subscription`
-          : 'Select start and end months'
-      }
-      required
-    />
+    <form>
+      <MonthRangePicker
+        label="Subscription Period"
+        value={duration}
+        onChange={(e) => setDuration(e.target.value)}
+        disablePast
+        helperText={monthsCount > 0 ? `${monthsCount} month subscription` : 'Select period'}
+        required
+      />
+      <Typography level="body-sm">
+        Total: ${monthsCount * 9.99}/period
+      </Typography>
+      <Button type="submit">Subscribe</Button>
+    </form>
+  );
+}
+```
+
+### Budget Planning
+
+```tsx
+function BudgetPlanningForm({ departments }) {
+  const [planningPeriod, setPlanningPeriod] = useState('');
+  const [allocations, setAllocations] = useState({});
+
+  // Default to next fiscal year
+  useEffect(() => {
+    const now = new Date();
+    const nextYear = now.getFullYear() + 1;
+    setPlanningPeriod(`${nextYear}/01 - ${nextYear}/12`);
+  }, []);
+
+  return (
+    <form>
+      <MonthRangePicker
+        label="Budget Planning Period"
+        value={planningPeriod}
+        onChange={(e) => setPlanningPeriod(e.target.value)}
+        format="YYYY/MM"
+        helperText="Select the months for budget allocation"
+      />
+
+      {planningPeriod && departments.map((dept) => (
+        <CurrencyInput
+          key={dept.id}
+          label={dept.name}
+          value={allocations[dept.id] || ''}
+          onChange={(value) => setAllocations(prev => ({
+            ...prev,
+            [dept.id]: value
+          }))}
+        />
+      ))}
+
+      <Button type="submit">Submit Budget Plan</Button>
+    </form>
   );
 }
 ```
@@ -284,14 +354,20 @@ function SubscriptionForm() {
 ```tsx
 function YearOverYearComparison() {
   const [currentPeriod, setCurrentPeriod] = useState('');
+  const [previousPeriod, setPreviousPeriod] = useState('');
 
-  const getPreviousPeriod = (value: string) => {
-    if (!value) return '';
-    const [start, end] = value.split(' - ');
-    const [sYear, sMonth] = start.split('/').map(Number);
-    const [eYear, eMonth] = end.split('/').map(Number);
-    return `${sYear - 1}/${String(sMonth).padStart(2, '0')} - ${eYear - 1}/${String(eMonth).padStart(2, '0')}`;
-  };
+  // Auto-calculate previous period
+  useEffect(() => {
+    if (!currentPeriod) return;
+
+    const [start, end] = currentPeriod.split(' - ');
+    const [startYear, startMonth] = start.split('/').map(Number);
+    const [endYear, endMonth] = end.split('/').map(Number);
+
+    const prevStart = `${startYear - 1}/${String(startMonth).padStart(2, '0')}`;
+    const prevEnd = `${endYear - 1}/${String(endMonth).padStart(2, '0')}`;
+    setPreviousPeriod(`${prevStart} - ${prevEnd}`);
+  }, [currentPeriod]);
 
   return (
     <Stack gap={2}>
@@ -303,69 +379,370 @@ function YearOverYearComparison() {
       />
       <MonthRangePicker
         label="Previous Period (Auto-calculated)"
-        value={getPreviousPeriod(currentPeriod)}
+        value={previousPeriod}
         disabled
       />
+      <Button disabled={!currentPeriod}>
+        Compare Periods
+      </Button>
     </Stack>
   );
 }
 ```
 
-## Best Practices
+### Seasonal Analysis
 
-1. **Match value format to `format` prop**: The `value` prop must follow the same pattern as `format`, with start and end separated by `-`.
+```tsx
+function SeasonalAnalysis() {
+  const [period, setPeriod] = useState('');
+
+  const getSeason = (monthRange) => {
+    if (!monthRange) return '';
+    const [start, end] = monthRange.split(' - ');
+    const startMonth = parseInt(start.split('/')[1]);
+    const endMonth = parseInt(end.split('/')[1]);
+
+    // Simple season detection based on months
+    if (startMonth >= 3 && endMonth <= 5) return 'Spring';
+    if (startMonth >= 6 && endMonth <= 8) return 'Summer';
+    if (startMonth >= 9 && endMonth <= 11) return 'Fall';
+    if ((startMonth >= 12 || startMonth <= 2)) return 'Winter';
+    return 'Custom Period';
+  };
+
+  return (
+    <Stack gap={2}>
+      <MonthRangePicker
+        label="Analysis Period"
+        value={period}
+        onChange={(e) => setPeriod(e.target.value)}
+        disableFuture
+      />
+      {period && (
+        <Typography level="body-sm">
+          Season: {getSeason(period)}
+        </Typography>
+      )}
+    </Stack>
+  );
+}
+```
+
+### Data Export with Range
+
+```tsx
+function DataExportForm() {
+  const [exportRange, setExportRange] = useState('');
+  const [isExporting, setIsExporting] = useState(false);
+
+  const handleExport = async () => {
+    if (!exportRange) return;
+
+    setIsExporting(true);
+    const [startMonth, endMonth] = exportRange.split(' - ');
+
+    try {
+      const response = await api.exportData({
+        startMonth: startMonth.replace('/', '-'),
+        endMonth: endMonth.replace('/', '-'),
+      });
+      downloadFile(response.data);
+    } finally {
+      setIsExporting(false);
+    }
+  };
+
+  return (
+    <Stack gap={2}>
+      <MonthRangePicker
+        label="Export Period"
+        value={exportRange}
+        onChange={(e) => setExportRange(e.target.value)}
+        format="YYYY/MM"
+        disableFuture
+        required
+      />
+      <Button
+        onClick={handleExport}
+        loading={isExporting}
+        disabled={!exportRange}
+      >
+        Export Data
+      </Button>
+    </Stack>
+  );
+}
+```
+
+## Props and Customization
+
+### Key Props
+
+| Prop            | Type                                                        | Default     | Description                              |
+| --------------- | ----------------------------------------------------------- | ----------- | ---------------------------------------- |
+| `value`         | `string`                                                    | -           | Controlled value (`"YYYY/MM - YYYY/MM"`) |
+| `defaultValue`  | `string`                                                    | -           | Default value for uncontrolled mode      |
+| `onChange`      | `(e: { target: { name?: string; value: string } }) => void` | -           | Change handler                           |
+| `format`        | `string`                                                    | `'YYYY/MM'` | Format for value and display             |
+| `label`         | `string`                                                    | -           | Label text                               |
+| `helperText`    | `string`                                                    | -           | Helper text below input                  |
+| `error`         | `boolean`                                                   | `false`     | Error state                              |
+| `size`          | `'sm' \| 'md' \| 'lg'`                                      | `'md'`      | Component size                           |
+| `disabled`      | `boolean`                                                   | `false`     | Disabled state                           |
+| `required`      | `boolean`                                                   | `false`     | Required field indicator                 |
+| `minDate`       | `string`                                                    | -           | Minimum selectable month                 |
+| `maxDate`       | `string`                                                    | -           | Maximum selectable month                 |
+| `disableFuture` | `boolean`                                                   | `false`     | Disable all future months                |
+| `disablePast`   | `boolean`                                                   | `false`     | Disable all past months                  |
+
+### Value Format
+
+The value is a string with start and end months separated by `-`:
+
+```tsx
+// Value format: "YYYY/MM - YYYY/MM"
+const value = "2024/04 - 2024/09";
+
+// Parsing the value
+const [startMonth, endMonth] = value.split(' - ');
+console.log(startMonth); // "2024/04"
+console.log(endMonth);   // "2024/09"
+```
+
+### Supported Format Tokens
+
+| Token  | Description   | Example |
+| ------ | ------------- | ------- |
+| `YYYY` | 4-digit year  | 2024    |
+| `MM`   | 2-digit month | 04      |
+
+Common format patterns:
+
+- `YYYY/MM` - Default (2024/04)
+- `YYYY-MM` - ISO-like (2024-04)
+- `MM/YYYY` - European (04/2024)
+- `YYYY.MM` - Period separator (2024.04)
+
+### Format Affects Both Display and Value
+
+Unlike DatePicker components, MonthRangePicker's `format` prop affects both the display and the value:
 
 ```tsx
-// ✅ Good: Matching formats
 <MonthRangePicker
-  format="YYYY/MM"
-  value="2024/04 - 2024/09"
+  format="YYYY-MM"  // Both display AND onChange value use this format
+  onChange={(e) => {
+    console.log(e.target.value); // "2024-04 - 2024-09"
+  }}
 />
+```
+
+### Controlled vs Uncontrolled
 
-// ❌ Bad: Mismatched format
+```tsx
+// Uncontrolled - component manages state
 <MonthRangePicker
-  format="YYYY/MM"
-  value="04/2024 - 09/2024"
+  defaultValue="2024/04 - 2024/09"
+  onChange={(e) => console.log(e.target.value)}
+/>
+
+// Controlled - you manage state
+const [monthRange, setMonthRange] = useState('2024/04 - 2024/09');
+<MonthRangePicker
+  value={monthRange}
+  onChange={(e) => setMonthRange(e.target.value)}
 />
 ```
 
-2. **Show range duration in helper text**: Help users understand the length of the period they selected.
+## Accessibility
+
+MonthRangePicker includes built-in accessibility features:
+
+### ARIA Attributes
+
+- Input has proper `role="textbox"`
+- Calendar button has `aria-label="Toggle Calendar"`
+- Month grid uses proper navigation roles
+- Selected months marked with `aria-selected`
+
+### Keyboard Navigation
+
+- **Tab**: Move focus between input and calendar button
+- **Enter/Space**: Open calendar when focused on button
+- **Arrow Keys**: Navigate between months in calendar
+- **Escape**: Close calendar popup
+- **Enter**: Select focused month
+
+### Screen Reader Support
+
+```tsx
+// Range selection is announced
+// First click: "Start month: April 2024"
+// Second click: "End month: September 2024"
+
+// Navigation buttons are descriptive
+<button aria-label="Previous Year">←</button>
+<button aria-label="Next Year">→</button>
+```
+
+### Focus Management
+
+- Focus moves to current year's month grid when opened
+- Focus returns to input when calendar closes
+- Clear visual focus indicators on all interactive elements
+- Range selection provides visual feedback between start and end months
+
+## Best Practices
+
+### ✅ Do
+
+1. **Validate month ranges**: Ensure start month is before end month
 
 ```tsx
-// ✅ Good: Dynamic helper text
+// ✅ Good: Validate the range
+const validateRange = (value) => {
+  const [start, end] = value.split(' - ');
+  const [startYear, startMonth] = start.split('/').map(Number);
+  const [endYear, endMonth] = end.split('/').map(Number);
+
+  if (startYear > endYear) return false;
+  if (startYear === endYear && startMonth > endMonth) return false;
+  return true;
+};
+```
+
+2. **Show range duration**: Help users understand the period length
+
+```tsx
+// ✅ Good: Display duration
+const getMonthsCount = (value) => {
+  if (!value) return 0;
+  const [start, end] = value.split(' - ');
+  const [startYear, startMonth] = start.split('/').map(Number);
+  const [endYear, endMonth] = end.split('/').map(Number);
+  return (endYear - startYear) * 12 + (endMonth - startMonth) + 1;
+};
+
 <MonthRangePicker
   helperText={`${getMonthsCount(range)} months selected`}
 />
 ```
 
-3. **Set reasonable date constraints**: Use `minDate`, `maxDate`, `disableFuture`, or `disablePast` to prevent invalid selections at the UI level.
+3. **Set reasonable limits**: Prevent excessively long ranges
 
 ```tsx
-// ✅ Good: Logical constraints for historical reporting
-<MonthRangePicker disableFuture minDate="2020/01" />
+// ✅ Good: Limit range span
+const MAX_MONTHS = 24;
+const validateMaxRange = (value) => {
+  return getMonthsCount(value) <= MAX_MONTHS;
+};
 ```
 
-4. **Validate before processing**: Always check that the value is non-empty and properly formed before parsing.
+4. **Use consistent formats**: Match your application's conventions
 
 ```tsx
-// ✅ Good: Guard against empty values
-const handleSubmit = () => {
-  if (!range || !range.includes(' - ')) return;
-  const [start, end] = range.split(' - ');
-  // process start and end
-};
+// ✅ Good: Consistent with app format
+<MonthRangePicker
+  format="YYYY-MM"  // ISO format for API compatibility
+/>
 ```
 
-5. **Use consistent `format` across your application**: Choose one format (e.g., `YYYY-MM` for API compatibility) and stick with it.
+### ❌ Don't
+
+1. **Don't allow invalid ranges**: Always validate start ≤ end
 
 ```tsx
-// ✅ Good: ISO format for API compatibility
-<MonthRangePicker format="YYYY-MM" />
+// ❌ Bad: No validation
+<MonthRangePicker onChange={(e) => setRange(e.target.value)} />
+
+// ✅ Good: Validate range
+<MonthRangePicker
+  onChange={(e) => {
+    if (isValidRange(e.target.value)) {
+      setRange(e.target.value);
+    }
+  }}
+/>
 ```
 
-## Accessibility
+2. **Don't use inconsistent value formats**: Match value to format prop
+
+```tsx
+// ❌ Bad: Mismatched formats
+<MonthRangePicker
+  format="YYYY/MM"
+  value="04/2024 - 09/2024"  // Wrong! Should use YYYY/MM
+/>
+
+// ✅ Good: Matching formats
+<MonthRangePicker
+  format="YYYY/MM"
+  value="2024/04 - 2024/09"
+/>
+```
+
+3. **Don't forget to handle empty states**: Validate before processing
+
+4. **Don't use for day-level selection**: Use DateRangePicker when days matter
+
+## Performance Considerations
+
+### Memoize Handlers
+
+When using MonthRangePicker in complex forms:
+
+```tsx
+const handleChange = useCallback((e) => {
+  setMonthRange(e.target.value);
+}, []);
+
+<MonthRangePicker value={monthRange} onChange={handleChange} />
+```
+
+### Parse Values Efficiently
+
+When processing month range values:
+
+```tsx
+const { startYear, startMonth, endYear, endMonth, monthsCount } = useMemo(() => {
+  if (!monthRange) return { startYear: null, startMonth: null, endYear: null, endMonth: null, monthsCount: 0 };
+
+  const [start, end] = monthRange.split(' - ');
+  const [startYear, startMonth] = start.split('/').map(Number);
+  const [endYear, endMonth] = end.split('/').map(Number);
+  const monthsCount = (endYear - startYear) * 12 + (endMonth - startMonth) + 1;
+
+  return { startYear, startMonth, endYear, endMonth, monthsCount };
+}, [monthRange]);
+```
+
+### Format Conversion for APIs
+
+When working with APIs that expect different formats:
+
+```tsx
+function MonthRangeField({ value, onChange, apiFormat = 'YYYY-MM' }) {
+  const displayFormat = 'YYYY/MM';
+
+  const convertToDisplay = (apiValue) => {
+    if (!apiValue) return '';
+    const [start, end] = apiValue.split(' - ');
+    return `${start.replace('-', '/')} - ${end.replace('-', '/')}`;
+  };
+
+  const convertToApi = (displayValue) => {
+    if (!displayValue) return '';
+    const [start, end] = displayValue.split(' - ');
+    return `${start.replace('/', '-')} - ${end.replace('/', '-')}`;
+  };
+
+  return (
+    <MonthRangePicker
+      value={convertToDisplay(value)}
+      onChange={(e) => onChange(convertToApi(e.target.value))}
+      format={displayFormat}
+    />
+  );
+}
+```
 
-- The input has `role="textbox"` and the calendar toggle button has `aria-label="Toggle Calendar"` for screen reader identification.
-- **Keyboard navigation**: Use **Tab** to move focus between the input and calendar button, **Enter/Space** to open the calendar, **Arrow Keys** to navigate months, and **Escape** to close the popup.
-- Range selection is conveyed through visual highlighting between the start and end months in the calendar grid. Each month button has a descriptive `aria-label` (e.g., "April 2024").
-- Focus management moves focus into the calendar grid when opened and returns focus to the input when the calendar is closed.
+MonthRangePicker provides an efficient way to select multi-month periods for fiscal reporting, budget planning, and data analysis. Remember that the `format` prop affects both display and value, and always validate that the start month precedes the end month.