@ceed/ads 1.29.0 → 1.30.0-next.1

package/dist/components/inputs/DatePicker.md

@@ -1,8 +1,8 @@
 # DatePicker
 
-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.
+## Introduction
 
-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.
+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.
 
 ```tsx
 <DatePicker onChange={fn()} />
@@ -28,6 +28,15 @@ DatePicker is essential for any form that requires date input -- booking systems
 | 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
@@ -46,14 +55,19 @@ function DateForm() {
 }
 ```
 
-> **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
+<DatePicker onChange={fn()} />
+```
 
-## Sizes
+### Sizes
 
-DatePicker supports three sizes (`sm`, `md`, `lg`) to fit different layout densities.
+DatePicker supports three sizes for different layouts.
 
 ```tsx
 <Stack gap={2}>
@@ -63,9 +77,9 @@ DatePicker supports three sizes (`sm`, `md`, `lg`) to fit different layout densi
 </Stack>
 ```
 
-## Label and Helper Text
+### With Label
 
-Use the `label` prop to provide a visible label, and `helperText` to give users additional guidance about expected input.
+Add a label above the date picker.
 
 ```tsx
 <DatePicker
@@ -74,6 +88,10 @@ Use the `label` prop to provide a visible label, and `helperText` to give users
 />
 ```
 
+### With Helper Text
+
+Provide additional guidance below the input.
+
 ```tsx
 <DatePicker
   onChange={fn()}
@@ -82,9 +100,9 @@ Use the `label` prop to provide a visible label, and `helperText` to give users
 />
 ```
 
-## Validation and Error State
+### Error State
 
-Set `error` to `true` and combine with `helperText` to communicate validation failures. Use the `required` prop to indicate mandatory fields.
+Show validation errors with error styling.
 
 ```tsx
 <DatePicker
@@ -95,6 +113,10 @@ Set `error` to `true` and combine with `helperText` to communicate validation fa
 />
 ```
 
+### Required Field
+
+Mark the field as required in forms.
+
 ```tsx
 <DatePicker
   onChange={fn()}
@@ -104,9 +126,9 @@ Set `error` to `true` and combine with `helperText` to communicate validation fa
 />
 ```
 
-## Disabled and Read-Only States
+### 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.
+Prevent user interaction when disabled.
 
 ```tsx
 <DatePicker
@@ -115,25 +137,9 @@ The `disabled` prop prevents all interaction. The `readOnly` prop displays the v
 />
 ```
 
-```tsx
-<DatePicker
-  onChange={fn()}
-  value="2024/04/01"
-  readOnly
-/>
-```
+### Minimum Date
 
-```tsx
-<DatePicker
-  onChange={fn()}
-  value="2024/04/01"
-  inputReadOnly
-/>
-```
-
-## Date Restrictions
-
-Restrict selectable dates using `minDate`, `maxDate`, `disablePast`, `disableFuture`, or the flexible `shouldDisableDate` callback for custom logic such as disabling weekends or holidays.
+Restrict selection to dates on or after a minimum date.
 
 ```tsx
 <DatePicker
@@ -142,6 +148,10 @@ Restrict selectable dates using `minDate`, `maxDate`, `disablePast`, `disableFut
 />
 ```
 
+### Maximum Date
+
+Restrict selection to dates on or before a maximum date.
+
 ```tsx
 <DatePicker
   onChange={fn()}
@@ -149,6 +159,10 @@ Restrict selectable dates using `minDate`, `maxDate`, `disablePast`, `disableFut
 />
 ```
 
+### Disable Future Dates
+
+Prevent selection of dates in the future.
+
 ```tsx
 <DatePicker
   onChange={fn()}
@@ -156,24 +170,20 @@ Restrict selectable dates using `minDate`, `maxDate`, `disablePast`, `disableFut
 />
 ```
 
-```tsx
-<DatePicker
-  onChange={fn()}
-  disablePast
-/>
-```
+### Disable Past Dates
+
+Prevent selection of dates in the past.
 
 ```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 vs Uncontrolled
+### Controlled
 
-DatePicker works in both controlled mode (you manage `value` via state) and uncontrolled mode (component manages its own state via `defaultValue`).
+Parent component manages the date state.
 
 ```tsx
 <Stack gap={2}>
@@ -191,6 +201,10 @@ DatePicker works in both controlled mode (you manage `value` via state) and unco
 </Stack>
 ```
 
+### Uncontrolled
+
+Component manages its own state internally.
+
 ```tsx
 <DatePicker
   onChange={fn()}
@@ -200,9 +214,9 @@ DatePicker works in both controlled mode (you manage `value` via state) and unco
 />
 ```
 
-## Format and Display Format
+### With Formats
 
-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`).
+Different value formats for the `onChange` event.
 
 ```tsx
 <Stack gap={2}>
@@ -215,6 +229,10 @@ The `format` prop determines the shape of the value emitted through `onChange`,
 </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 => {
@@ -244,38 +262,33 @@ The `format` prop determines the shape of the value emitted through `onChange`,
 </Stack>
 ```
 
-**Supported format tokens:**
+### Input Read Only
 
-| Token  | Description   | Example |
-| ------ | ------------- | ------- |
-| `YYYY` | 4-digit year  | 2024    |
-| `MM`   | 2-digit month | 04      |
-| `DD`   | 2-digit day   | 15      |
-
-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).
+Allow calendar selection only, prevent typing.
 
-## Additional Features
+```tsx
+<DatePicker
+  onChange={fn()}
+  value="2024/04/01"
+  inputReadOnly
+/>
+```
 
-### Reset Button
+### Read Only
 
-Pair DatePicker with an external reset button to programmatically clear the value.
+Fully read-only state with no interaction.
 
 ```tsx
-<div style={{
-  display: 'flex',
-  gap: '10px'
-}}>
-<DatePicker {...props} value={value} onChange={event => {
-  onChange?.(event);
-  setValue(event.target.value);
-}} />
-<Button onClick={() => setValue('')}>Reset</Button>
-</div>
+<DatePicker
+  onChange={fn()}
+  value="2024/04/01"
+  readOnly
+/>
 ```
 
 ### Hide Clear Button
 
-Remove the built-in clear button from the calendar popup when clearing is not desired.
+Remove the clear button from the calendar popup.
 
 ```tsx
 <DatePicker
@@ -285,9 +298,21 @@ Remove the built-in clear button from the calendar popup when clearing is not de
 />
 ```
 
+### 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 DatePicker instances can share the same value for dependent field scenarios.
+Multiple date pickers sharing the same value.
 
 ```tsx
 <Stack gap={2}>
@@ -299,6 +324,25 @@ Multiple DatePicker instances can share the same value for dependent field scena
 </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
@@ -313,6 +357,7 @@ function BookingForm() {
       setError('Please select a check-in date');
       return;
     }
+    // Submit form
   };
 
   return (
@@ -329,21 +374,62 @@ function BookingForm() {
         disablePast
         required
       />
+      <Button type="submit">Book Now</Button>
     </form>
   );
 }
 ```
 
-### Custom Date Disabling (Weekdays Only)
+### 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
 
 ```tsx
 function AppointmentPicker() {
   const [date, setDate] = useState('');
 
-  const shouldDisableDate = useCallback((dateString: string) => {
-    const day = new Date(dateString).getDay();
-    return day === 0 || day === 6; // Disable weekends
-  }, []);
+  // 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;
+  };
 
   return (
     <DatePicker
@@ -352,89 +438,326 @@ function AppointmentPicker() {
       onChange={(e) => setDate(e.target.value)}
       shouldDisableDate={shouldDisableDate}
       disablePast
-      helperText="Weekdays only"
+      helperText="Weekdays only, excluding holidays"
     />
   );
 }
 ```
 
-### Locale-Aware Display
+### Different Regional Formats
 
 ```tsx
-function RegionalDateField({ locale }: { locale: string }) {
+function RegionalDateForm({ locale }) {
   const [date, setDate] = useState('');
 
-  const displayFormat = locale === 'en-US' ? 'MM/DD/YYYY'
-    : locale === 'en-GB' ? 'DD/MM/YYYY'
-    : 'YYYY-MM-DD';
+  // 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';
+    }
+  };
 
   return (
     <DatePicker
       label="Date"
       value={date}
       onChange={(e) => setDate(e.target.value)}
-      format="YYYY/MM/DD"
-      displayFormat={displayFormat}
+      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
     />
   );
 }
 ```
 
+### 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
 
-1. **Always provide a label**
+### ✅ Do
+
+1. **Use appropriate date restrictions**: Set min/max dates when applicable
 
 ```tsx
-{/* Do */}
-<DatePicker label="Birth Date" />
+// ✅ Good: Reasonable date constraints
+<DatePicker
+  label="Birth Date"
+  disableFuture
+  minDate="1900/01/01"
+/>
+```
 
-{/* Don't */}
-<DatePicker placeholder="Birth Date" />
+2. **Provide clear labels and helper text**: Guide users on expected input
+
+```tsx
+// ✅ Good: Clear guidance
+<DatePicker
+  label="Preferred Delivery Date"
+  helperText="Select a weekday within the next 2 weeks"
+/>
 ```
 
-2. **Keep value format consistent with the `format` prop**
+3. **Use consistent formats**: Match your application's locale conventions
 
 ```tsx
-{/* Do */}
-<DatePicker format="YYYY/MM/DD" value="2024/04/15" />
+// ✅ Good: Consistent with app locale
+<DatePicker
+  format="YYYY-MM-DD"  // API format
+  displayFormat="MM/DD/YYYY"  // US locale display
+/>
+```
 
-{/* Don't -- mismatched format causes unexpected behavior */}
-<DatePicker format="YYYY/MM/DD" value="04/15/2024" />
+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>}
 ```
 
-3. **Use `displayFormat` to separate API format from UI format**
+### ❌ Don't
+
+1. **Don't use inconsistent value formats**: Always match value format to `format` prop
 
 ```tsx
-{/* Do -- consistent API format, locale-appropriate display */}
-<DatePicker format="YYYY-MM-DD" displayFormat="MM/DD/YYYY" />
+// ❌ Bad: Mismatched formats
+<DatePicker
+  format="YYYY/MM/DD"
+  value="04/15/2024"  // Wrong! Should be "2024/04/15"
+/>
+```
 
-{/* Don't -- changing format just for display affects onChange values */}
-<DatePicker format="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} />
 ```
 
-4. **Set appropriate date boundaries for your use case**
+3. **Don't forget mobile users**: Use `inputReadOnly` for better mobile experience
+
+4. **Don't use placeholder as label**: Use the `label` prop instead
 
 ```tsx
-{/* Do */}
-<DatePicker label="Birth Date" disableFuture minDate="1900/01/01" />
+// ❌ Bad: Placeholder as label
+<DatePicker placeholder="Birth Date" />
 
-{/* Don't -- unrestricted date range for a birth date field */}
+// ✅ Good: Proper label
 <DatePicker label="Birth Date" />
 ```
 
-5. **Show validation feedback with error and helperText**
+## Performance Considerations
+
+### Memoize shouldDisableDate
+
+For complex date validation logic, memoize the function:
 
 ```tsx
-{/* Do */}
-<DatePicker error={!isValid} helperText={errorMessage} />
+const shouldDisableDate = useCallback((dateString) => {
+  const date = new Date(dateString);
+  // Complex validation logic
+  return isHoliday(date) || isWeekend(date);
+}, [holidays]); // Only recreate when holidays change
 
-{/* Don't -- silently ignore invalid state */}
-<DatePicker value={invalidDate} />
+<DatePicker shouldDisableDate={shouldDisableDate} />
 ```
 
-## Accessibility
+### 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} />
+```
+
+### 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"
+    />
+  );
+}
+```
 
-- **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.
+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.