@ceed/cds 1.24.1-next.3 → 1.25.0

package/dist/components/inputs/DatePicker.md

@@ -1,8 +1,8 @@
 # DatePicker
 
-## Introduction
+DatePicker is a form input component that allows users to select a single date from a calendar popup or by typing directly into the input field. It provides flexible date formatting options, date range restrictions, and supports both controlled and uncontrolled modes.
 
-DatePicker is a form input component that allows users to select a single date from a calendar popup or by typing directly into the input field. It provides flexible date formatting options, date range restrictions, and supports both controlled and uncontrolled modes. DatePicker is essential for forms that require date input, such as booking systems, scheduling interfaces, and data filtering.
+DatePicker is essential for any form that requires date input -- booking systems, scheduling interfaces, data filtering, and record keeping. It handles the complexity of date parsing, formatting, and validation so consumers can focus on business logic.
 
 ```tsx
 <DatePicker onChange={fn()} />
@@ -28,15 +28,6 @@ DatePicker is a form input component that allows users to select a single date f
 | disableFuture   | —           | —       |
 | disablePast     | —           | —       |
 
-> ⚠️ **Usage Warning** ⚠️
->
-> DatePicker involves complex date handling logic:
->
-> - **Format vs DisplayFormat**: `format` affects the value in `onChange`, while `displayFormat` affects what users see
-> - **Value format consistency**: The `value` and `defaultValue` props must match the `format` prop
-> - **Date validation**: Invalid date strings can cause unexpected behavior
-> - **Timezone considerations**: Be aware of timezone issues when working with dates
-
 ## Usage
 
 ```tsx
@@ -55,19 +46,14 @@ function DateForm() {
 }
 ```
 
-## Examples
-
-### Playground
-
-Interactive example with all controls.
-
-```tsx
-<DatePicker onChange={fn()} />
-```
+> **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
 
-DatePicker supports three sizes for different layouts.
+DatePicker supports three sizes (`sm`, `md`, `lg`) to fit different layout densities.
 
 ```tsx
 <Stack gap={2}>
@@ -77,9 +63,9 @@ DatePicker supports three sizes for different layouts.
 </Stack>
 ```
 
-### With Label
+## Label and Helper Text
 
-Add a label above the date picker.
+Use the `label` prop to provide a visible label, and `helperText` to give users additional guidance about expected input.
 
 ```tsx
 <DatePicker
@@ -88,10 +74,6 @@ Add a label above the date picker.
 />
 ```
 
-### With Helper Text
-
-Provide additional guidance below the input.
-
 ```tsx
 <DatePicker
   onChange={fn()}
@@ -100,9 +82,9 @@ Provide additional guidance below the input.
 />
 ```
 
-### Error State
+## Validation and Error State
 
-Show validation errors with error styling.
+Set `error` to `true` and combine with `helperText` to communicate validation failures. Use the `required` prop to indicate mandatory fields.
 
 ```tsx
 <DatePicker
@@ -113,10 +95,6 @@ Show validation errors with error styling.
 />
 ```
 
-### Required Field
-
-Mark the field as required in forms.
-
 ```tsx
 <DatePicker
   onChange={fn()}
@@ -126,9 +104,9 @@ Mark the field as required in forms.
 />
 ```
 
-### Disabled
+## Disabled and Read-Only States
 
-Prevent user interaction when disabled.
+The `disabled` prop prevents all interaction. The `readOnly` prop displays the value but blocks changes, while `inputReadOnly` disables keyboard typing but still allows calendar selection -- useful for mobile scenarios.
 
 ```tsx
 <DatePicker
@@ -137,31 +115,39 @@ Prevent user interaction when disabled.
 />
 ```
 
-### Minimum Date
-
-Restrict selection to dates on or after a minimum date.
+```tsx
+<DatePicker
+  onChange={fn()}
+  value="2024/04/01"
+  readOnly
+/>
+```
 
 ```tsx
 <DatePicker
   onChange={fn()}
-  minDate="2024-04-10"
+  value="2024/04/01"
+  inputReadOnly
 />
 ```
 
-### Maximum Date
+## Date Restrictions
 
-Restrict selection to dates on or before a maximum date.
+Restrict selectable dates using `minDate`, `maxDate`, `disablePast`, `disableFuture`, or the flexible `shouldDisableDate` callback for custom logic such as disabling weekends or holidays.
 
 ```tsx
 <DatePicker
   onChange={fn()}
-  maxDate="2024-04-10"
+  minDate="2024-04-10"
 />
 ```
 
-### Disable Future Dates
-
-Prevent selection of dates in the future.
+```tsx
+<DatePicker
+  onChange={fn()}
+  maxDate="2024-04-10"
+/>
+```
 
 ```tsx
 <DatePicker
@@ -170,20 +156,24 @@ Prevent selection of dates in the future.
 />
 ```
 
-### Disable Past Dates
-
-Prevent selection of dates in the past.
+```tsx
+<DatePicker
+  onChange={fn()}
+  disablePast
+/>
+```
 
 ```tsx
 <DatePicker
   onChange={fn()}
   disablePast
+  shouldDisableDate={date => [0, 6].includes(new Date(date).getDay()) || new Date(date).getTime() >= new Date().getTime() + 7 * 24 * 60 * 60 * 1000}
 />
 ```
 
-### Controlled
+## Controlled vs Uncontrolled
 
-Parent component manages the date state.
+DatePicker works in both controlled mode (you manage `value` via state) and uncontrolled mode (component manages its own state via `defaultValue`).
 
 ```tsx
 <Stack gap={2}>
@@ -201,10 +191,6 @@ Parent component manages the date state.
 </Stack>
 ```
 
-### Uncontrolled
-
-Component manages its own state internally.
-
 ```tsx
 <DatePicker
   onChange={fn()}
@@ -214,9 +200,9 @@ Component manages its own state internally.
 />
 ```
 
-### With Formats
+## Format and Display Format
 
-Different value formats for the `onChange` event.
+The `format` prop determines the shape of the value emitted through `onChange`, while `displayFormat` controls what users see in the input field. This separation lets you keep a consistent API format (e.g. `YYYY-MM-DD`) while displaying a locale-appropriate format (e.g. `MM/DD/YYYY`).
 
 ```tsx
 <Stack gap={2}>
@@ -229,10 +215,6 @@ Different value formats for the `onChange` event.
 </Stack>
 ```
 
-### With Display Formats
-
-Different display formats shown in the input field.
-
 ```tsx
 <Stack gap={2}>
   <DatePicker {...args} value={value1} label="YYYY.MM.DD" name="YYYY.MM.DD" displayFormat="YYYY.MM.DD" onChange={e => {
@@ -262,33 +244,38 @@ Different display formats shown in the input field.
 </Stack>
 ```
 
-### Input Read Only
+**Supported format tokens:**
 
-Allow calendar selection only, prevent typing.
+| Token  | Description   | Example |
+| ------ | ------------- | ------- |
+| `YYYY` | 4-digit year  | 2024    |
+| `MM`   | 2-digit month | 04      |
+| `DD`   | 2-digit day   | 15      |
 
-```tsx
-<DatePicker
-  onChange={fn()}
-  value="2024/04/01"
-  inputReadOnly
-/>
-```
+Common patterns: `YYYY/MM/DD` (default), `YYYY-MM-DD` (ISO 8601), `MM/DD/YYYY` (US), `DD/MM/YYYY` (EU), `DD.MM.YYYY` (German), `YYYY.MM.DD` (East Asian).
+
+## Additional Features
 
-### Read Only
+### Reset Button
 
-Fully read-only state with no interaction.
+Pair DatePicker with an external reset button to programmatically clear the value.
 
 ```tsx
-<DatePicker
-  onChange={fn()}
-  value="2024/04/01"
-  readOnly
-/>
+<div style={{
+  display: 'flex',
+  gap: '10px'
+}}>
+<DatePicker {...props} value={value} onChange={event => {
+  onChange?.(event);
+  setValue(event.target.value);
+}} />
+<Button onClick={() => setValue('')}>Reset</Button>
+</div>
 ```
 
 ### Hide Clear Button
 
-Remove the clear button from the calendar popup.
+Remove the built-in clear button from the calendar popup when clearing is not desired.
 
 ```tsx
 <DatePicker
@@ -298,21 +285,9 @@ Remove the clear button from the calendar popup.
 />
 ```
 
-### Custom Date Disabling
-
-Use `shouldDisableDate` to disable specific dates.
-
-```tsx
-<DatePicker
-  onChange={fn()}
-  disablePast
-  shouldDisableDate={date => [0, 6].includes(new Date(date).getDay()) || new Date(date).getTime() >= new Date().getTime() + 7 * 24 * 60 * 60 * 1000}
-/>
-```
-
 ### Synchronized Date Pickers
 
-Multiple date pickers sharing the same value.
+Multiple DatePicker instances can share the same value for dependent field scenarios.
 
 ```tsx
 <Stack gap={2}>
@@ -324,25 +299,6 @@ Multiple date pickers sharing the same value.
 </Stack>
 ```
 
-## When to Use
-
-### ✅ Good Use Cases
-
-- **Form date fields**: Birthdays, appointment dates, due dates
-- **Booking systems**: Hotel check-in/out, flight dates, reservations
-- **Scheduling**: Event dates, meeting times, deadlines
-- **Data filtering**: Date range filters in reports and dashboards
-- **Historical data**: Recording when events occurred
-- **Deadline selection**: Task due dates, project milestones
-
-### ❌ When Not to Use
-
-- **Date ranges**: Use DateRangePicker for start/end date pairs
-- **Month/Year only**: Use MonthPicker for month-level granularity
-- **Time selection**: Use a dedicated TimePicker component
-- **Relative dates**: For "last 7 days" style filters, use dropdown selection
-- **Known date sets**: For selecting from predefined dates, consider Select or RadioButton
-
 ## Common Use Cases
 
 ### Form with Validation
@@ -357,7 +313,6 @@ function BookingForm() {
       setError('Please select a check-in date');
       return;
     }
-    // Submit form
   };
 
   return (
@@ -374,62 +329,21 @@ function BookingForm() {
         disablePast
         required
       />
-      <Button type="submit">Book Now</Button>
     </form>
   );
 }
 ```
 
-### Date Range Restriction
-
-```tsx
-function EventScheduler() {
-  const [eventDate, setEventDate] = useState('');
-
-  // Event must be within the next 30 days
-  const today = new Date();
-  const maxDate = new Date(today.getTime() + 30 * 24 * 60 * 60 * 1000);
-
-  const formatDate = (date) => {
-    const year = date.getFullYear();
-    const month = String(date.getMonth() + 1).padStart(2, '0');
-    const day = String(date.getDate()).padStart(2, '0');
-    return `${year}/${month}/${day}`;
-  };
-
-  return (
-    <DatePicker
-      label="Event Date"
-      value={eventDate}
-      onChange={(e) => setEventDate(e.target.value)}
-      minDate={formatDate(today)}
-      maxDate={formatDate(maxDate)}
-      helperText="Select a date within the next 30 days"
-    />
-  );
-}
-```
-
-### Custom Date Validation
+### Custom Date Disabling (Weekdays Only)
 
 ```tsx
 function AppointmentPicker() {
   const [date, setDate] = useState('');
 
-  // Disable weekends and holidays
-  const shouldDisableDate = (dateString) => {
-    const date = new Date(dateString);
-    const day = date.getDay();
-
-    // Disable weekends (Saturday = 6, Sunday = 0)
-    if (day === 0 || day === 6) return true;
-
-    // Disable specific holidays
-    const holidays = ['2024/01/01', '2024/12/25'];
-    if (holidays.includes(dateString)) return true;
-
-    return false;
-  };
+  const shouldDisableDate = useCallback((dateString: string) => {
+    const day = new Date(dateString).getDay();
+    return day === 0 || day === 6; // Disable weekends
+  }, []);
 
   return (
     <DatePicker
@@ -438,326 +352,89 @@ function AppointmentPicker() {
       onChange={(e) => setDate(e.target.value)}
       shouldDisableDate={shouldDisableDate}
       disablePast
-      helperText="Weekdays only, excluding holidays"
+      helperText="Weekdays only"
     />
   );
 }
 ```
 
-### Different Regional Formats
+### Locale-Aware Display
 
 ```tsx
-function RegionalDateForm({ locale }) {
+function RegionalDateField({ locale }: { locale: string }) {
   const [date, setDate] = useState('');
 
-  // Format based on locale
-  const getDisplayFormat = () => {
-    switch (locale) {
-      case 'en-US':
-        return 'MM/DD/YYYY';
-      case 'en-GB':
-        return 'DD/MM/YYYY';
-      case 'de-DE':
-        return 'DD.MM.YYYY';
-      default:
-        return 'YYYY/MM/DD';
-    }
-  };
+  const displayFormat = locale === 'en-US' ? 'MM/DD/YYYY'
+    : locale === 'en-GB' ? 'DD/MM/YYYY'
+    : 'YYYY-MM-DD';
 
   return (
     <DatePicker
       label="Date"
       value={date}
       onChange={(e) => setDate(e.target.value)}
-      format="YYYY/MM/DD"  // Internal value format stays consistent
-      displayFormat={getDisplayFormat()}  // Display varies by locale
-    />
-  );
-}
-```
-
-### Mobile-Friendly Input
-
-```tsx
-function MobileDatePicker() {
-  const [date, setDate] = useState('');
-
-  return (
-    <DatePicker
-      label="Select Date"
-      value={date}
-      onChange={(e) => setDate(e.target.value)}
-      inputReadOnly  // Prevent keyboard on mobile, use calendar only
-      size="lg"  // Larger touch targets
+      format="YYYY/MM/DD"
+      displayFormat={displayFormat}
     />
   );
 }
 ```
 
-### Form Integration with React Hook Form
-
-```tsx
-function DateFormWithHookForm() {
-  const { register, handleSubmit, setValue, watch } = useForm();
-  const birthDate = watch('birthDate');
-
-  return (
-    <form onSubmit={handleSubmit(onSubmit)}>
-      <DatePicker
-        label="Birth Date"
-        value={birthDate || ''}
-        onChange={(e) => setValue('birthDate', e.target.value)}
-        disableFuture
-        required
-      />
-    </form>
-  );
-}
-```
-
-## Props and Customization
-
-### Key Props
-
-| Prop                | Type                                                        | Default          | Description                                 |
-| ------------------- | ----------------------------------------------------------- | ---------------- | ------------------------------------------- |
-| `value`             | `string`                                                    | -                | Controlled date value (must match `format`) |
-| `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`                                                    | Same as `format` | 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 date                     |
-| `maxDate`           | `string`                                                    | -                | Maximum selectable date                     |
-| `disableFuture`     | `boolean`                                                   | `false`          | Disable all future dates                    |
-| `disablePast`       | `boolean`                                                   | `false`          | Disable all past dates                      |
-| `shouldDisableDate` | `(date: string) => boolean`                                 | -                | Custom date disable function                |
-| `inputReadOnly`     | `boolean`                                                   | `false`          | Prevent typing, calendar only               |
-| `readOnly`          | `boolean`                                                   | `false`          | Fully read-only                             |
-| `hideClearButton`   | `boolean`                                                   | `false`          | Hide clear button in calendar               |
-
-### Format vs DisplayFormat
-
-Understanding the difference between `format` and `displayFormat`:
-
-```tsx
-// format: Affects the value in onChange
-// displayFormat: Affects what users see in the input
-
-<DatePicker
-  format="YYYY-MM-DD"      // onChange returns "2024-04-15"
-  displayFormat="MM/DD/YYYY" // Input shows "04/15/2024"
-  onChange={(e) => {
-    console.log(e.target.value); // "2024-04-15"
-  }}
-/>
-```
-
-### Supported Format Tokens
-
-| Token  | Description   | Example |
-| ------ | ------------- | ------- |
-| `YYYY` | 4-digit year  | 2024    |
-| `MM`   | 2-digit month | 04      |
-| `DD`   | 2-digit day   | 15      |
-
-Common format patterns:
-
-- `YYYY/MM/DD` - ISO-like (default)
-- `YYYY-MM-DD` - ISO 8601
-- `MM/DD/YYYY` - US format
-- `DD/MM/YYYY` - European format
-- `DD.MM.YYYY` - German format
-- `YYYY.MM.DD` - East Asian format
-
-### Controlled vs Uncontrolled
-
-```tsx
-// Uncontrolled - component manages state
-<DatePicker
-  defaultValue="2024/04/01"
-  onChange={(e) => console.log(e.target.value)}
-/>
-
-// Controlled - you manage state
-const [date, setDate] = useState('2024/04/01');
-<DatePicker
-  value={date}
-  onChange={(e) => setDate(e.target.value)}
-/>
-```
-
-## Accessibility
-
-DatePicker includes built-in accessibility features:
-
-### ARIA Attributes
-
-- Input has proper `role="textbox"`
-- Calendar button has `aria-label="Toggle Calendar"`
-- Calendar popup uses `role="tooltip"` with proper labeling
-- Date buttons announce the full date to screen readers
-
-### Keyboard Navigation
-
-- **Tab**: Move focus between input and calendar button
-- **Enter/Space**: Open calendar when focused on button
-- **Arrow Keys**: Navigate within calendar
-- **Escape**: Close calendar popup
-- **Enter**: Select focused date
-
-### Screen Reader Support
-
-```tsx
-// Dates are announced with full context
-<button aria-label="April 15, 2024">15</button>
-
-// Navigation buttons are descriptive
-<button aria-label="Previous Month">←</button>
-<button aria-label="Next Month">→</button>
-```
-
-### Focus Management
-
-- Focus moves to calendar when opened
-- Focus returns to input when calendar closes
-- Clear visual focus indicators on all interactive elements
-
 ## Best Practices
 
-### ✅ Do
-
-1. **Use appropriate date restrictions**: Set min/max dates when applicable
+1. **Always provide a label**
 
 ```tsx
-// ✅ Good: Reasonable date constraints
-<DatePicker
-  label="Birth Date"
-  disableFuture
-  minDate="1900/01/01"
-/>
-```
-
-2. **Provide clear labels and helper text**: Guide users on expected input
+{/* Do */}
+<DatePicker label="Birth Date" />
 
-```tsx
-// ✅ Good: Clear guidance
-<DatePicker
-  label="Preferred Delivery Date"
-  helperText="Select a weekday within the next 2 weeks"
-/>
+{/* Don't */}
+<DatePicker placeholder="Birth Date" />
 ```
 
-3. **Use consistent formats**: Match your application's locale conventions
+2. **Keep value format consistent with the `format` prop**
 
 ```tsx
-// ✅ Good: Consistent with app locale
-<DatePicker
-  format="YYYY-MM-DD"  // API format
-  displayFormat="MM/DD/YYYY"  // US locale display
-/>
-```
+{/* Do */}
+<DatePicker format="YYYY/MM/DD" value="2024/04/15" />
 
-4. **Handle empty states**: Consider what empty value means in your context
-
-```tsx
-// ✅ Good: Clear empty state handling
-const [date, setDate] = useState('');
-{date ? <span>Selected: {date}</span> : <span>No date selected</span>}
+{/* Don't -- mismatched format causes unexpected behavior */}
+<DatePicker format="YYYY/MM/DD" value="04/15/2024" />
 ```
 
-### ❌ Don't
-
-1. **Don't use inconsistent value formats**: Always match value format to `format` prop
+3. **Use `displayFormat` to separate API format from UI format**
 
 ```tsx
-// ❌ Bad: Mismatched formats
-<DatePicker
-  format="YYYY/MM/DD"
-  value="04/15/2024"  // Wrong! Should be "2024/04/15"
-/>
-```
+{/* Do -- consistent API format, locale-appropriate display */}
+<DatePicker format="YYYY-MM-DD" displayFormat="MM/DD/YYYY" />
 
-2. **Don't disable validation feedback**: Show errors when dates are invalid
-
-```tsx
-// ❌ Bad: No error feedback
-<DatePicker value={invalidDate} />
-
-// ✅ Good: Show validation state
-<DatePicker value={date} error={!isValid} helperText={errorMessage} />
+{/* Don't -- changing format just for display affects onChange values */}
+<DatePicker format="MM/DD/YYYY" />
 ```
 
-3. **Don't forget mobile users**: Use `inputReadOnly` for better mobile experience
-
-4. **Don't use placeholder as label**: Use the `label` prop instead
+4. **Set appropriate date boundaries for your use case**
 
 ```tsx
-// ❌ Bad: Placeholder as label
-<DatePicker placeholder="Birth Date" />
+{/* Do */}
+<DatePicker label="Birth Date" disableFuture minDate="1900/01/01" />
 
-// ✅ Good: Proper label
+{/* Don't -- unrestricted date range for a birth date field */}
 <DatePicker label="Birth Date" />
 ```
 
-## Performance Considerations
-
-### Memoize shouldDisableDate
-
-For complex date validation logic, memoize the function:
+5. **Show validation feedback with error and helperText**
 
 ```tsx
-const shouldDisableDate = useCallback((dateString) => {
-  const date = new Date(dateString);
-  // Complex validation logic
-  return isHoliday(date) || isWeekend(date);
-}, [holidays]); // Only recreate when holidays change
-
-<DatePicker shouldDisableDate={shouldDisableDate} />
-```
+{/* Do */}
+<DatePicker error={!isValid} helperText={errorMessage} />
 
-### Controlled Component Optimization
-
-When using controlled mode, avoid unnecessary state updates:
-
-```tsx
-const handleChange = useCallback((e) => {
-  setDate(e.target.value);
-}, []);
-
-<DatePicker value={date} onChange={handleChange} />
+{/* Don't -- silently ignore invalid state */}
+<DatePicker value={invalidDate} />
 ```
 
-### Format Conversion
-
-When working with APIs that expect different date formats:
-
-```tsx
-function DateField({ value, onChange, apiFormat = 'YYYY-MM-DD' }) {
-  // Convert from API format to display
-  const displayValue = useMemo(() =>
-    convertFormat(value, apiFormat, 'YYYY/MM/DD'),
-    [value, apiFormat]
-  );
-
-  const handleChange = useCallback((e) => {
-    // Convert back to API format
-    onChange(convertFormat(e.target.value, 'YYYY/MM/DD', apiFormat));
-  }, [onChange, apiFormat]);
-
-  return (
-    <DatePicker
-      value={displayValue}
-      onChange={handleChange}
-      format="YYYY/MM/DD"
-    />
-  );
-}
-```
+## Accessibility
 
-DatePicker is a fundamental form component for date input. Choose appropriate date restrictions based on your use case, maintain consistent formats throughout your application, and provide clear guidance to users for the best experience.
+- **Keyboard navigation**: Tab moves focus between the input and the calendar toggle button. Arrow keys navigate dates within the open calendar. Enter selects the focused date, and Escape closes the calendar popup.
+- **ARIA attributes**: The calendar toggle button has `aria-label="Toggle Calendar"`. The calendar popup uses `role="tooltip"` with descriptive labeling. Each date button announces the full date to screen readers.
+- **Focus management**: Focus moves into the calendar when opened and returns to the input when the calendar closes. All interactive elements have clear focus indicators.
+- **Use `inputReadOnly` on mobile**: When targeting touch devices, set `inputReadOnly` to prevent the virtual keyboard from appearing and guide users toward the calendar picker instead.