@ceed/cds 1.24.1-next.3 → 1.25.0

package/dist/components/inputs/MonthPicker.md

@@ -2,7 +2,9 @@
 
 ## Introduction
 
-MonthPicker is a form input component that allows users to select a specific month and year from a calendar popup. Unlike DatePicker which allows day-level selection, MonthPicker focuses on month-level granularity. It displays months in a grid format for easy selection and is ideal for scenarios like billing periods, report months, subscription dates, or any use case where day-level precision is unnecessary.
+MonthPicker is a form input component that allows users to select a specific month and year from a calendar popup. Unlike DatePicker which provides day-level selection, MonthPicker focuses on month-level granularity and displays months in a grid format for quick selection.
+
+It is ideal for scenarios like billing periods, report months, subscription dates, or any use case where day-level precision is unnecessary. The component supports multiple value formats and display formats, controlled and uncontrolled modes, and date range constraints.
 
 ```tsx
 <MonthPicker />
@@ -25,15 +27,6 @@ MonthPicker is a form input component that allows users to select a specific mon
 | format        | —           | —       |
 | onChange      | —           | —       |
 
-> ⚠️ **Usage Warning** ⚠️
->
-> MonthPicker has some unique formatting behaviors:
->
-> - **Internal value format**: Values internally use full date format (`"YYYY/MM/DD"`) with day set to `01`
-> - **Display vs Value**: Input displays `YYYY/MM` but `onChange` receives `YYYY/MM/01`
-> - **Format consistency**: Ensure your `value` prop matches the `format` prop
-> - **displayFormat options**: Supports special token `MMMM` for full month names
-
 ## Usage
 
 ```tsx
@@ -52,19 +45,14 @@ function MonthForm() {
 }
 ```
 
-## Examples
-
-### Playground
-
-Interactive example with all controls.
-
-```tsx
-<MonthPicker />
-```
+> 💡 **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
 
-MonthPicker supports three sizes for different layouts.
+MonthPicker supports three sizes (`sm`, `md`, `lg`) for different layouts and contexts.
 
 ```tsx
 <Stack gap={2}>
@@ -74,9 +62,11 @@ MonthPicker supports three sizes for different layouts.
 </Stack>
 ```
 
+## Form Field Features
+
 ### With Label
 
-Add a label above the month picker.
+Add a label above the month picker to indicate the field purpose.
 
 ```tsx
 <MonthPicker label="Date" />
@@ -84,7 +74,7 @@ Add a label above the month picker.
 
 ### With Helper Text
 
-Provide additional guidance below the input.
+Provide additional guidance below the input to help users understand the expected selection.
 
 ```tsx
 <MonthPicker
@@ -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
 <MonthPicker
-  label="Date"
-  helperText="Please select a date"
-  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
 <MonthPicker
-  label="Label"
-  helperText="I'm helper text"
-  required
+  label="Date"
+  helperText="Please select a date"
+  error
 />
 ```
 
 ### Disabled
 
-Prevent user interaction when disabled.
+Prevent user interaction when the picker is disabled.
 
 ```tsx
 <MonthPicker 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
 <MonthPicker 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
 <MonthPicker 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
 <MonthPicker 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
 <MonthPicker disablePast />
 ```
 
+## Controlled vs Uncontrolled
+
 ### Controlled
 
-Parent component manages the month state.
+The parent component manages the month state via the `value` and `onChange` props. External buttons or logic can programmatically update the selected value.
 
 ```tsx
 <Stack gap={2}>
@@ -178,7 +172,7 @@ Parent component manages the month 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
 <MonthPicker
@@ -188,9 +182,11 @@ Component manages its own state internally.
 />
 ```
 
-### With Formats
+## Formats
 
-Different value formats for the `onChange` event.
+### Value Formats
+
+The `format` prop determines the shape of the value emitted by `onChange`. Each format includes a day component (set to `01`). The display always defaults to `YYYY/MM` unless `displayFormat` is also set.
 
 ```tsx
 <Stack gap={2}>
@@ -203,9 +199,9 @@ Different value formats for the `onChange` event.
 </Stack>
 ```
 
-### With Display Formats
+### Display Formats
 
-Different display formats including full month names.
+The `displayFormat` prop controls what users see in the input field, independent of the underlying value format. Supports the special token `MMMM` for full month names.
 
 ```tsx
 <Stack gap={2}>
@@ -236,24 +232,21 @@ Different display formats including full month names.
 </Stack>
 ```
 
-## When to Use
-
-### ✅ Good Use Cases
-
-- **Billing periods**: Monthly invoices, subscription billing cycles
-- **Report filtering**: Monthly reports, quarterly summaries
-- **Fiscal periods**: Fiscal months, budget allocation periods
-- **Expiration dates**: Credit card expiry (month/year)
-- **Historical data**: Selecting past months for data analysis
-- **Scheduling**: Monthly recurring events
+### With Reset Button
 
-### ❌ When Not to Use
+A controlled example with an external reset button to clear the selected value.
 
-- **Specific dates**: Use DatePicker when day selection matters
-- **Date ranges**: Use DateRangePicker or MonthRangePicker
-- **Week selection**: Consider a custom week picker
-- **Quarter selection**: Consider a dropdown with Q1-Q4 options
-- **Year only**: Use a year picker or simple dropdown
+```tsx
+<div style={{
+  display: 'flex',
+  gap: '10px'
+}}>
+<MonthPicker {...props} value={value} onChange={event => {
+  setValue(event.target.value);
+}} />
+<Button onClick={() => setValue('')}>Reset</Button>
+</div>
+```
 
 ## Common Use Cases
 
@@ -263,55 +256,32 @@ Different display formats including full month names.
 function BillingPeriodSelector() {
   const [billingMonth, setBillingMonth] = useState('');
 
-  const handleGenerate = () => {
-    const [year, month] = billingMonth.split('/');
-    generateInvoice({ year: parseInt(year), month: parseInt(month) });
-  };
-
   return (
-    <Stack gap={2}>
-      <MonthPicker
-        label="Billing Period"
-        value={billingMonth}
-        onChange={(e) => setBillingMonth(e.target.value)}
-        disableFuture
-        helperText="Select the month for invoice generation"
-      />
-      <Button onClick={handleGenerate} disabled={!billingMonth}>
-        Generate Invoice
-      </Button>
-    </Stack>
+    <MonthPicker
+      label="Billing Period"
+      value={billingMonth}
+      onChange={(e) => setBillingMonth(e.target.value)}
+      disableFuture
+      helperText="Select the month for invoice generation"
+    />
   );
 }
 ```
 
-### Report Month Filter
+### Report Month Filter with Display Format
 
 ```tsx
-function ReportFilters({ onFilter }) {
+function ReportFilter() {
   const [reportMonth, setReportMonth] = useState('');
 
-  // Get current month as default
-  useEffect(() => {
-    const now = new Date();
-    const year = now.getFullYear();
-    const month = String(now.getMonth() + 1).padStart(2, '0');
-    setReportMonth(`${year}/${month}/01`);
-  }, []);
-
   return (
-    <Stack direction="row" gap={2} alignItems="flex-end">
-      <MonthPicker
-        label="Report Month"
-        value={reportMonth}
-        onChange={(e) => setReportMonth(e.target.value)}
-        disableFuture
-        displayFormat="MMMM YYYY"  // Shows "January 2024"
-      />
-      <Button onClick={() => onFilter(reportMonth)}>
-        Generate Report
-      </Button>
-    </Stack>
+    <MonthPicker
+      label="Report Month"
+      value={reportMonth}
+      onChange={(e) => setReportMonth(e.target.value)}
+      disableFuture
+      displayFormat="MMMM YYYY"
+    />
   );
 }
 ```
@@ -322,7 +292,6 @@ function ReportFilters({ onFilter }) {
 function CreditCardExpiry() {
   const [expiry, setExpiry] = useState('');
 
-  // Get current date for minimum
   const today = new Date();
   const minDate = `${today.getFullYear()}/${String(today.getMonth() + 1).padStart(2, '0')}/01`;
 
@@ -332,7 +301,7 @@ function CreditCardExpiry() {
       value={expiry}
       onChange={(e) => setExpiry(e.target.value)}
       minDate={minDate}
-      displayFormat="MM/YYYY"  // Common credit card format
+      displayFormat="MM/YYYY"
       helperText="Enter card expiration date"
       required
     />
@@ -340,355 +309,59 @@ function CreditCardExpiry() {
 }
 ```
 
-### Fiscal Period Selector
-
-```tsx
-function FiscalPeriodSelector({ fiscalYearStart = 4 }) { // April
-  const [selectedMonth, setSelectedMonth] = useState('');
-  const [fiscalPeriod, setFiscalPeriod] = useState('');
-
-  // Calculate fiscal period from selected month
-  useEffect(() => {
-    if (!selectedMonth) return;
-
-    const [year, month] = selectedMonth.split('/').map(Number);
-    const fiscalMonth = month >= fiscalYearStart
-      ? month - fiscalYearStart + 1
-      : month + (12 - fiscalYearStart + 1);
-    const fiscalYear = month >= fiscalYearStart ? year : year - 1;
-
-    setFiscalPeriod(`FY${fiscalYear} P${fiscalMonth}`);
-  }, [selectedMonth, fiscalYearStart]);
-
-  return (
-    <Stack gap={2}>
-      <MonthPicker
-        label="Select Period"
-        value={selectedMonth}
-        onChange={(e) => setSelectedMonth(e.target.value)}
-        displayFormat="MMMM YYYY"
-      />
-      {fiscalPeriod && (
-        <Typography level="body-sm">Fiscal Period: {fiscalPeriod}</Typography>
-      )}
-    </Stack>
-  );
-}
-```
-
-### Monthly Budget Allocation
-
-```tsx
-function BudgetAllocation({ departments }) {
-  const [selectedMonth, setSelectedMonth] = useState('');
-  const [budgets, setBudgets] = useState({});
-
-  // Restrict to future months only
-  const today = new Date();
-  const nextMonth = new Date(today.getFullYear(), today.getMonth() + 1, 1);
-  const minDate = `${nextMonth.getFullYear()}/${String(nextMonth.getMonth() + 1).padStart(2, '0')}/01`;
-
-  return (
-    <form>
-      <MonthPicker
-        label="Budget Month"
-        value={selectedMonth}
-        onChange={(e) => setSelectedMonth(e.target.value)}
-        minDate={minDate}
-        displayFormat="MMMM YYYY"
-        helperText="Select month for budget allocation"
-        required
-      />
-
-      {selectedMonth && departments.map((dept) => (
-        <CurrencyInput
-          key={dept.id}
-          label={`${dept.name} Budget`}
-          value={budgets[dept.id] || ''}
-          onChange={(value) => setBudgets(prev => ({
-            ...prev,
-            [dept.id]: value
-          }))}
-        />
-      ))}
-
-      <Button type="submit">Allocate Budget</Button>
-    </form>
-  );
-}
-```
-
-### Year-Month Comparison
-
-```tsx
-function MonthComparison() {
-  const [month1, setMonth1] = useState('');
-  const [month2, setMonth2] = useState('');
-
-  return (
-    <Stack gap={2}>
-      <Stack direction="row" gap={2}>
-        <MonthPicker
-          label="Compare From"
-          value={month1}
-          onChange={(e) => setMonth1(e.target.value)}
-          disableFuture
-        />
-        <MonthPicker
-          label="Compare To"
-          value={month2}
-          onChange={(e) => setMonth2(e.target.value)}
-          disableFuture
-          minDate={month1}  // Must be after first month
-        />
-      </Stack>
-      <Button disabled={!month1 || !month2}>
-        Compare Months
-      </Button>
-    </Stack>
-  );
-}
-```
-
-## Props and Customization
-
-### Key Props
-
-| Prop            | Type                                                        | Default        | Description                             |
-| --------------- | ----------------------------------------------------------- | -------------- | --------------------------------------- |
-| `value`         | `string`                                                    | -              | Controlled value (format: `YYYY/MM/DD`) |
-| `defaultValue`  | `string`                                                    | -              | Default value for uncontrolled mode     |
-| `onChange`      | `(e: { target: { name?: string; value: string } }) => void` | -              | Change handler                          |
-| `format`        | `string`                                                    | `'YYYY/MM/DD'` | Format for `value` and `onChange`       |
-| `displayFormat` | `string`                                                    | `'YYYY/MM'`    | Format displayed in the input           |
-| `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                 |
-
-### Display Format Tokens
-
-| Token  | Description     | Example |
-| ------ | --------------- | ------- |
-| `YYYY` | 4-digit year    | 2024    |
-| `MM`   | 2-digit month   | 04      |
-| `DD`   | 2-digit day     | 01      |
-| `MMMM` | Full month name | January |
-
-Common display format patterns:
-
-- `YYYY/MM` - Default (2024/04)
-- `YYYY-MM` - ISO-like (2024-04)
-- `MM/YYYY` - European (04/2024)
-- `MMMM YYYY` - Full name (April 2024)
-- `YYYY.MM` - Period separator (2024.04)
-
-### Value Format Understanding
-
-```tsx
-// MonthPicker always uses day=01 in values
-// Even though display shows "2024/04", the value is "2024/04/01"
-
-<MonthPicker
-  value="2024/04/01"  // Must include day
-  displayFormat="YYYY/MM"  // Shows "2024/04"
-  onChange={(e) => {
-    console.log(e.target.value); // "2024/04/01"
-    // Extract just year and month
-    const [year, month] = e.target.value.split('/');
-    console.log(`${year}-${month}`); // "2024-04"
-  }}
-/>
-```
-
-### Format vs DisplayFormat
-
-```tsx
-// format: Affects the value in onChange
-// displayFormat: Affects what users see in the input
-
-<MonthPicker
-  format="YYYY-MM-DD"      // onChange returns "2024-04-01"
-  displayFormat="MMMM YYYY" // Input shows "April 2024"
-  onChange={(e) => {
-    console.log(e.target.value); // "2024-04-01"
-  }}
-/>
-```
-
-### Controlled vs Uncontrolled
-
-```tsx
-// Uncontrolled - component manages state
-<MonthPicker
-  defaultValue="2024/04/01"
-  onChange={(e) => console.log(e.target.value)}
-/>
-
-// Controlled - you manage state
-const [month, setMonth] = useState('2024/04/01');
-<MonthPicker
-  value={month}
-  onChange={(e) => setMonth(e.target.value)}
-/>
-```
-
-## Accessibility
-
-MonthPicker 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 month 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
+## Best Practices
 
-### Screen Reader Support
+1. **Match value format to `format` prop**: The `value` prop must follow the same pattern as `format`. Mismatches cause unexpected behavior.
 
 ```tsx
-// Months are announced with full context
-<button aria-label="April 2024">Apr</button>
+// ✅ Good: Value matches default format
+<MonthPicker value="2024/04/01" />
 
-// Navigation buttons are descriptive
-<button aria-label="Previous Year">←</button>
-<button aria-label="Next Year">→</button>
+// ❌ Bad: Value missing the day component
+<MonthPicker value="2024/04" />
 ```
 
-### 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
-
-## Best Practices
-
-### ✅ Do
-
-1. **Use appropriate display formats**: Match the display format to user expectations
+2. **Use `displayFormat` for user-friendly presentation**: Keep the value format stable for programmatic use, and customize only the visible representation.
 
 ```tsx
-// ✅ Good: User-friendly display format
+// ✅ Good: Separate concerns
 <MonthPicker
-  displayFormat="MMMM YYYY"  // "January 2024" is clearer
-  label="Billing Month"
+  format="YYYY/MM/DD"
+  displayFormat="MMMM YYYY"
 />
 ```
 
-2. **Set reasonable date limits**: Restrict months based on context
+3. **Provide context with `helperText`**: Guide users on what they are selecting, especially when constraints are applied.
 
 ```tsx
-// ✅ Good: Logical constraints for billing
+// ✅ Good: Clear guidance
 <MonthPicker
-  disableFuture  // Can't bill for future months
-  minDate="2020/01/01"  // Company started in 2020
+  label="Statement Month"
+  helperText="Select the month for your account statement"
+  disableFuture
 />
 ```
 
-3. **Provide context in helper text**: Guide users on selection purpose
+4. **Set reasonable date constraints**: Use `minDate`, `maxDate`, `disableFuture`, or `disablePast` to prevent invalid selections at the UI level.
 
 ```tsx
-// ✅ Good: Clear guidance
-<MonthPicker
-  label="Statement Month"
-  helperText="Select the month for your account statement"
-/>
+// ✅ Good: Logical constraints
+<MonthPicker disableFuture minDate="2020/01/01" />
 ```
 
-4. **Handle the day value**: Remember values include day set to 01
+5. **Handle the day component in values**: Remember that `onChange` values always include a day set to `01`. Extract year and month when only those parts are needed.
 
 ```tsx
-// ✅ Good: Extract month/year when needed
+// ✅ Good: Extract month/year
 const handleChange = (e) => {
   const [year, month] = e.target.value.split('/');
   setSelectedPeriod({ year: parseInt(year), month: parseInt(month) });
 };
 ```
 
-### ❌ Don't
-
-1. **Don't expect day-only display in values**: Values always include day
-
-```tsx
-// ❌ Bad: Expecting value without day
-<MonthPicker
-  value="2024/04"  // Wrong! Needs "2024/04/01"
-/>
-
-// ✅ Good: Full value format
-<MonthPicker
-  value="2024/04/01"
-/>
-```
-
-2. **Don't use inconsistent formats**: Match value format to format prop
-
-```tsx
-// ❌ Bad: Mismatched formats
-<MonthPicker
-  format="YYYY/MM/DD"
-  value="04/2024"  // Wrong format
-/>
-```
-
-3. **Don't forget to handle empty states**: Validate before processing
-
-4. **Don't use for day-level selection**: Use DatePicker when days matter
-
-## Performance Considerations
-
-### Memoize Handlers
-
-When using MonthPicker in complex forms:
-
-```tsx
-const handleChange = useCallback((e) => {
-  setMonth(e.target.value);
-}, []);
-
-<MonthPicker value={month} onChange={handleChange} />
-```
-
-### Extract Month/Year Efficiently
-
-When you need just the month and year:
-
-```tsx
-const { year, month } = useMemo(() => {
-  if (!selectedMonth) return { year: null, month: null };
-  const [year, month] = selectedMonth.split('/').map(Number);
-  return { year, month };
-}, [selectedMonth]);
-```
-
-### Date Calculations
-
-For fiscal year or period calculations:
-
-```tsx
-const fiscalData = useMemo(() => {
-  if (!selectedMonth) return null;
-
-  const [year, month] = selectedMonth.split('/').map(Number);
-  const fiscalYear = month >= 4 ? year : year - 1;
-  const fiscalQuarter = Math.ceil((month >= 4 ? month - 3 : month + 9) / 3);
-
-  return { fiscalYear, fiscalQuarter };
-}, [selectedMonth]);
-```
+## Accessibility
 
-MonthPicker simplifies month-level date selection for billing, reporting, and scheduling scenarios. Remember that values always include day (set to 01), and use displayFormat to show user-friendly month representations like full month names.
+- 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.
+- Each month button in the calendar grid has a descriptive `aria-label` (e.g., "April 2024") so screen readers announce the full context.
+- Focus management moves focus into the calendar grid when opened and returns focus to the input when the calendar is closed.