@ceed/ads 1.29.1 → 1.30.0-next.1

package/dist/components/inputs/MonthPicker.md

@@ -2,9 +2,7 @@
 
 ## Introduction
 
-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.
+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.
 
 ```tsx
 <MonthPicker />
@@ -27,6 +25,15 @@ It is ideal for scenarios like billing periods, report months, subscription date
 | 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
@@ -45,14 +52,19 @@ function MonthForm() {
 }
 ```
 
-> 💡 **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
+
+### Playground
+
+Interactive example with all controls.
+
+```tsx
+<MonthPicker />
+```
 
-## Sizes
+### Sizes
 
-MonthPicker supports three sizes (`sm`, `md`, `lg`) for different layouts and contexts.
+MonthPicker supports three sizes for different layouts.
 
 ```tsx
 <Stack gap={2}>
@@ -62,11 +74,9 @@ MonthPicker supports three sizes (`sm`, `md`, `lg`) for different layouts and co
 </Stack>
 ```
 
-## Form Field Features
-
 ### With Label
 
-Add a label above the month picker to indicate the field purpose.
+Add a label above the month picker.
 
 ```tsx
 <MonthPicker label="Date" />
@@ -74,7 +84,7 @@ Add a label above the month 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
 <MonthPicker
@@ -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
 <MonthPicker
-  label="Label"
-  helperText="I'm helper text"
-  required
+  label="Date"
+  helperText="Please select a date"
+  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
 <MonthPicker
-  label="Date"
-  helperText="Please select a date"
-  error
+  label="Label"
+  helperText="I'm helper text"
+  required
 />
 ```
 
 ### Disabled
 
-Prevent user interaction when the picker is disabled.
+Prevent user interaction when disabled.
 
 ```tsx
 <MonthPicker 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
 <MonthPicker 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
 <MonthPicker 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
 <MonthPicker 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
 <MonthPicker disablePast />
 ```
 
-## Controlled vs Uncontrolled
-
 ### Controlled
 
-The parent component manages the month state via the `value` and `onChange` props. External buttons or logic can programmatically update the selected value.
+Parent component manages the month state.
 
 ```tsx
 <Stack gap={2}>
@@ -172,7 +178,7 @@ The parent component manages the month state via the `value` and `onChange` prop
 
 ### 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
 <MonthPicker
@@ -182,11 +188,9 @@ The component manages its own state internally using `defaultValue`. The parent
 />
 ```
 
-## Formats
+### With Formats
 
-### 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.
+Different value formats for the `onChange` event.
 
 ```tsx
 <Stack gap={2}>
@@ -199,9 +203,9 @@ The `format` prop determines the shape of the value emitted by `onChange`. Each
 </Stack>
 ```
 
-### Display Formats
+### With Display Formats
 
-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.
+Different display formats including full month names.
 
 ```tsx
 <Stack gap={2}>
@@ -232,21 +236,24 @@ The `displayFormat` prop controls what users see in the input field, independent
 </Stack>
 ```
 
-### With Reset Button
+## When to Use
 
-A controlled example with an external reset button to clear the selected value.
+### ✅ Good Use Cases
 
-```tsx
-<div style={{
-  display: 'flex',
-  gap: '10px'
-}}>
-<MonthPicker {...props} value={value} onChange={event => {
-  setValue(event.target.value);
-}} />
-<Button onClick={() => setValue('')}>Reset</Button>
-</div>
-```
+- **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
+
+### ❌ When Not to Use
+
+- **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
 
 ## Common Use Cases
 
@@ -256,32 +263,55 @@ A controlled example with an external reset button to clear the selected value.
 function BillingPeriodSelector() {
   const [billingMonth, setBillingMonth] = useState('');
 
+  const handleGenerate = () => {
+    const [year, month] = billingMonth.split('/');
+    generateInvoice({ year: parseInt(year), month: parseInt(month) });
+  };
+
   return (
-    <MonthPicker
-      label="Billing Period"
-      value={billingMonth}
-      onChange={(e) => setBillingMonth(e.target.value)}
-      disableFuture
-      helperText="Select the month for invoice generation"
-    />
+    <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>
   );
 }
 ```
 
-### Report Month Filter with Display Format
+### Report Month Filter
 
 ```tsx
-function ReportFilter() {
+function ReportFilters({ onFilter }) {
   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 (
-    <MonthPicker
-      label="Report Month"
-      value={reportMonth}
-      onChange={(e) => setReportMonth(e.target.value)}
-      disableFuture
-      displayFormat="MMMM YYYY"
-    />
+    <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>
   );
 }
 ```
@@ -292,6 +322,7 @@ function ReportFilter() {
 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`;
 
@@ -301,7 +332,7 @@ function CreditCardExpiry() {
       value={expiry}
       onChange={(e) => setExpiry(e.target.value)}
       minDate={minDate}
-      displayFormat="MM/YYYY"
+      displayFormat="MM/YYYY"  // Common credit card format
       helperText="Enter card expiration date"
       required
     />
@@ -309,59 +340,355 @@ function CreditCardExpiry() {
 }
 ```
 
-## Best Practices
+### 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>
+  );
+}
+```
 
-1. **Match value format to `format` prop**: The `value` prop must follow the same pattern as `format`. Mismatches cause unexpected behavior.
+### Year-Month Comparison
 
 ```tsx
-// ✅ Good: Value matches default format
-<MonthPicker value="2024/04/01" />
+function MonthComparison() {
+  const [month1, setMonth1] = useState('');
+  const [month2, setMonth2] = useState('');
 
-// ❌ Bad: Value missing the day component
-<MonthPicker value="2024/04" />
+  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>
+  );
+}
 ```
 
-2. **Use `displayFormat` for user-friendly presentation**: Keep the value format stable for programmatic use, and customize only the visible representation.
+## 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
-// ✅ Good: Separate concerns
+// MonthPicker always uses day=01 in values
+// Even though display shows "2024/04", the value is "2024/04/01"
+
 <MonthPicker
-  format="YYYY/MM/DD"
-  displayFormat="MMMM YYYY"
+  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"
+  }}
 />
 ```
 
-3. **Provide context with `helperText`**: Guide users on what they are selecting, especially when constraints are applied.
+### Format vs DisplayFormat
 
 ```tsx
-// ✅ Good: Clear guidance
+// format: Affects the value in onChange
+// displayFormat: Affects what users see in the input
+
 <MonthPicker
-  label="Statement Month"
-  helperText="Select the month for your account statement"
-  disableFuture
+  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"
+  }}
 />
 ```
 
-4. **Set reasonable date constraints**: Use `minDate`, `maxDate`, `disableFuture`, or `disablePast` to prevent invalid selections at the UI level.
+### Controlled vs Uncontrolled
 
 ```tsx
-// ✅ Good: Logical constraints
-<MonthPicker disableFuture minDate="2020/01/01" />
+// 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)}
+/>
 ```
 
-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.
+## 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
+
+### Screen Reader Support
+
+```tsx
+// Months are announced with full context
+<button aria-label="April 2024">Apr</button>
+
+// 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
+
+## Best Practices
+
+### ✅ Do
+
+1. **Use appropriate display formats**: Match the display format to user expectations
+
+```tsx
+// ✅ Good: User-friendly display format
+<MonthPicker
+  displayFormat="MMMM YYYY"  // "January 2024" is clearer
+  label="Billing Month"
+/>
+```
+
+2. **Set reasonable date limits**: Restrict months based on context
+
+```tsx
+// ✅ Good: Logical constraints for billing
+<MonthPicker
+  disableFuture  // Can't bill for future months
+  minDate="2020/01/01"  // Company started in 2020
+/>
+```
+
+3. **Provide context in helper text**: Guide users on selection purpose
+
+```tsx
+// ✅ Good: Clear guidance
+<MonthPicker
+  label="Statement Month"
+  helperText="Select the month for your account statement"
+/>
+```
+
+4. **Handle the day value**: Remember values include day set to 01
 
 ```tsx
-// ✅ Good: Extract month/year
+// ✅ Good: Extract month/year when needed
 const handleChange = (e) => {
   const [year, month] = e.target.value.split('/');
   setSelectedPeriod({ year: parseInt(year), month: parseInt(month) });
 };
 ```
 
-## Accessibility
+### ❌ 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]);
+```
 
-- 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.
+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.