@ceed/cds 1.24.1-next.3 → 1.25.0

package/dist/components/inputs/MonthRangePicker.md

@@ -2,7 +2,9 @@
 
 ## 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. 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.
+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.
 
 ```tsx
 <MonthRangePicker />
@@ -25,15 +27,6 @@ MonthRangePicker is a form input component that allows users to select a range o
 | 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
@@ -52,19 +45,14 @@ function MonthRangeForm() {
 }
 ```
 
-## Examples
-
-### Playground
-
-Interactive example with all controls.
-
-```tsx
-<MonthRangePicker />
-```
+> 💡 **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.
 
-### Sizes
+## Sizes
 
-MonthRangePicker supports three sizes for different layouts.
+MonthRangePicker supports three sizes (`sm`, `md`, `lg`) for different layouts and contexts.
 
 ```tsx
 <Stack gap={2}>
@@ -74,9 +62,11 @@ MonthRangePicker supports three sizes for different layouts.
 </Stack>
 ```
 
+## Form Field Features
+
 ### With Label
 
-Add a label above the month range picker.
+Add a label above the month range picker to indicate the field purpose.
 
 ```tsx
 <MonthRangePicker label="Month Range" />
@@ -84,7 +74,7 @@ Add a label above the month range picker.
 
 ### With Helper Text
 
-Provide additional guidance below the input.
+Provide additional guidance below the input to help users understand the expected selection.
 
 ```tsx
 <MonthRangePicker
@@ -93,41 +83,43 @@ Provide additional guidance below the input.
 />
 ```
 
-### Error State
+### Required Field
 
-Show validation errors with error styling.
+Mark the field as required in forms. An asterisk indicator is displayed alongside the label.
 
 ```tsx
 <MonthRangePicker
-  label="Month"
-  helperText="Please select a month"
-  error
+  label="Label"
+  helperText="I'm helper text"
+  required
 />
 ```
 
-### Required Field
+### Error State
 
-Mark the field as required in forms.
+Display validation errors with error styling applied to the input, label, and helper text.
 
 ```tsx
 <MonthRangePicker
-  label="Label"
-  helperText="I'm helper text"
-  required
+  label="Month"
+  helperText="Please select a month"
+  error
 />
 ```
 
 ### Disabled
 
-Prevent user interaction when disabled.
+Prevent user interaction when the picker is disabled.
 
 ```tsx
 <MonthRangePicker disabled />
 ```
 
+## Date Constraints
+
 ### Minimum Date
 
-Restrict selection to months on or after a minimum date.
+Restrict selection to months on or after a minimum date. Months before the limit are visually disabled.
 
 ```tsx
 <MonthRangePicker minDate="2024-04-10" />
@@ -135,7 +127,7 @@ Restrict selection to months on or after a minimum date.
 
 ### Maximum Date
 
-Restrict selection to months on or before a maximum date.
+Restrict selection to months on or before a maximum date. Months after the limit are visually disabled.
 
 ```tsx
 <MonthRangePicker maxDate="2024-04-10" />
@@ -143,7 +135,7 @@ Restrict selection to months on or before a maximum date.
 
 ### Disable Future
 
-Prevent selection of months in the future.
+Prevent selection of any month in the future, relative to the current date.
 
 ```tsx
 <MonthRangePicker disableFuture />
@@ -151,15 +143,17 @@ Prevent selection of months in the future.
 
 ### Disable Past
 
-Prevent selection of months in the past.
+Prevent selection of any month in the past, relative to the current date.
 
 ```tsx
 <MonthRangePicker disablePast />
 ```
 
+## Controlled vs Uncontrolled
+
 ### Controlled
 
-Parent component manages the month range state.
+The parent component manages the month range state via the `value` and `onChange` props. External buttons or logic can programmatically update the selected range.
 
 ```tsx
 <Stack gap={2}>
@@ -182,7 +176,7 @@ Parent component manages the month range state.
 
 ### Uncontrolled
 
-Component manages its own state internally.
+The component manages its own state internally using `defaultValue`. The parent can still listen for changes via `onChange`.
 
 ```tsx
 <MonthRangePicker
@@ -192,9 +186,11 @@ Component manages its own state internally.
 />
 ```
 
-### With Formats
+## 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.
 
-Different value formats for regional preferences.
+The value is a string with start and end months separated by `-` (e.g., `"2024/04 - 2024/09"`).
 
 ```tsx
 <Stack gap={2}>
@@ -207,7 +203,7 @@ Different value formats for regional preferences.
 
 ### With Reset Button
 
-Example with an external reset button.
+A controlled example with an external reset button to clear the selected range.
 
 ```tsx
 <div style={{
@@ -221,25 +217,6 @@ Example with an external reset button.
 </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
@@ -271,14 +248,13 @@ function FiscalReportSelector() {
 }
 ```
 
-### Subscription Duration
+### Subscription Duration with Month Count
 
 ```tsx
 function SubscriptionForm() {
   const [duration, setDuration] = useState('');
 
-  // Calculate months count
-  const getMonthsCount = (value) => {
+  const getMonthsCount = (value: string) => {
     if (!value) return 0;
     const [start, end] = value.split(' - ');
     const [startYear, startMonth] = start.split('/').map(Number);
@@ -286,65 +262,19 @@ function SubscriptionForm() {
     return (endYear - startYear) * 12 + (endMonth - startMonth) + 1;
   };
 
-  const monthsCount = getMonthsCount(duration);
-
   return (
-    <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>
+    <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
+    />
   );
 }
 ```
@@ -354,20 +284,14 @@ function BudgetPlanningForm({ departments }) {
 ```tsx
 function YearOverYearComparison() {
   const [currentPeriod, setCurrentPeriod] = useState('');
-  const [previousPeriod, setPreviousPeriod] = useState('');
 
-  // 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]);
+  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')}`;
+  };
 
   return (
     <Stack gap={2}>
@@ -379,370 +303,69 @@ function YearOverYearComparison() {
       />
       <MonthRangePicker
         label="Previous Period (Auto-calculated)"
-        value={previousPeriod}
+        value={getPreviousPeriod(currentPeriod)}
         disabled
       />
-      <Button disabled={!currentPeriod}>
-        Compare Periods
-      </Button>
     </Stack>
   );
 }
 ```
 
-### Seasonal Analysis
-
-```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
-<MonthRangePicker
-  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
-
-```tsx
-// Uncontrolled - component manages state
-<MonthRangePicker
-  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)}
-/>
-```
-
-## 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: 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
+1. **Match value format to `format` prop**: The `value` prop must follow the same pattern as `format`, with start and end separated by `-`.
 
 ```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;
-};
-
+// ✅ Good: Matching formats
 <MonthRangePicker
-  helperText={`${getMonthsCount(range)} months selected`}
+  format="YYYY/MM"
+  value="2024/04 - 2024/09"
 />
-```
-
-3. **Set reasonable limits**: Prevent excessively long ranges
-
-```tsx
-// ✅ Good: Limit range span
-const MAX_MONTHS = 24;
-const validateMaxRange = (value) => {
-  return getMonthsCount(value) <= MAX_MONTHS;
-};
-```
-
-4. **Use consistent formats**: Match your application's conventions
 
-```tsx
-// ✅ Good: Consistent with app format
+// ❌ Bad: Mismatched format
 <MonthRangePicker
-  format="YYYY-MM"  // ISO format for API compatibility
+  format="YYYY/MM"
+  value="04/2024 - 09/2024"
 />
 ```
 
-### ❌ Don't
-
-1. **Don't allow invalid ranges**: Always validate start ≤ end
+2. **Show range duration in helper text**: Help users understand the length of the period they selected.
 
 ```tsx
-// ❌ Bad: No validation
-<MonthRangePicker onChange={(e) => setRange(e.target.value)} />
-
-// ✅ Good: Validate range
+// ✅ Good: Dynamic helper text
 <MonthRangePicker
-  onChange={(e) => {
-    if (isValidRange(e.target.value)) {
-      setRange(e.target.value);
-    }
-  }}
+  helperText={`${getMonthsCount(range)} months selected`}
 />
 ```
 
-2. **Don't use inconsistent value formats**: Match value to format prop
+3. **Set reasonable date constraints**: Use `minDate`, `maxDate`, `disableFuture`, or `disablePast` to prevent invalid selections at the UI level.
 
 ```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"
-/>
+// ✅ Good: Logical constraints for historical reporting
+<MonthRangePicker disableFuture minDate="2020/01" />
 ```
 
-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:
+4. **Validate before processing**: Always check that the value is non-empty and properly formed before parsing.
 
 ```tsx
-const handleChange = useCallback((e) => {
-  setMonthRange(e.target.value);
-}, []);
-
-<MonthRangePicker value={monthRange} onChange={handleChange} />
+// ✅ Good: Guard against empty values
+const handleSubmit = () => {
+  if (!range || !range.includes(' - ')) return;
+  const [start, end] = range.split(' - ');
+  // process start and end
+};
 ```
 
-### Parse Values Efficiently
-
-When processing month range values:
+5. **Use consistent `format` across your application**: Choose one format (e.g., `YYYY-MM` for API compatibility) and stick with it.
 
 ```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]);
+// ✅ Good: ISO format for API compatibility
+<MonthRangePicker format="YYYY-MM" />
 ```
 
-### 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}
-    />
-  );
-}
-```
+## Accessibility
 
-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.
+- 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.