@ceed/ads 1.29.1 → 1.30.0-next.1

package/dist/components/inputs/DateRangePicker.md

@@ -2,9 +2,7 @@
 
 ## Introduction
 
-DateRangePicker is a form input component that allows users to select a date range (start date and end date) from a calendar popup or by typing directly into the input field. It supports flexible date formatting, date restrictions, and both controlled and uncontrolled modes.
-
-DateRangePicker is ideal for booking systems, reporting filters, scheduling, and any scenario requiring a start-to-end date selection. For single date selection, use DatePicker instead. For month-level granularity, use MonthRangePicker.
+DateRangePicker is a form input component that allows users to select a date range (start date and end 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. DateRangePicker is ideal for booking systems, reporting filters, scheduling, and any scenario requiring a start-to-end date selection.
 
 ```tsx
 <DateRangePicker onChange={onChange} />
@@ -30,22 +28,14 @@ DateRangePicker is ideal for booking systems, reporting filters, scheduling, and
 | hideClearButton | —           | —       |
 | size            | —           | —       |
 
-> **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.
+> ⚠️ **Usage Warning** ⚠️
 >
-> ```tsx
-> // Recommended: use built-in props
-> <DateRangePicker label="Period" helperText="Select start and end dates" />
+> DateRangePicker involves complex date range handling:
 >
-> // Not recommended: manually composing with Typography
-> <FormControl>
->   <Typography level="title-sm" component="label">Period</Typography>
->   <DateRangePicker />
->   <Typography level="body-xs" color="neutral">Select start and end dates</Typography>
-> </FormControl>
-> ```
+> - **Value format**: Values use the format `"startDate - endDate"` (e.g., `"2024/04/01 - 2024/04/15"`)
+> - **Format consistency**: Both dates must match the `format` prop
+> - **Start/End validation**: Ensure start date is before end date
+> - **Range span**: Consider maximum range limits for performance and UX
 
 ## Usage
 
@@ -65,9 +55,19 @@ function DateRangeForm() {
 }
 ```
 
-## Sizes
+## Examples
 
-DateRangePicker supports three sizes (`sm`, `md`, `lg`) to fit different layouts and density requirements.
+### Playground
+
+Interactive example with all controls.
+
+```tsx
+<DateRangePicker onChange={onChange} />
+```
+
+### Sizes
+
+DateRangePicker supports three sizes for different layouts.
 
 ```tsx
 <Stack gap={2}>
@@ -77,11 +77,20 @@ DateRangePicker supports three sizes (`sm`, `md`, `lg`) to fit different layouts
 </Stack>
 ```
 
-## Form Features
+### Disabled
+
+Prevent user interaction when disabled.
+
+```tsx
+<DateRangePicker
+  onChange={onChange}
+  disabled
+/>
+```
 
-### Label
+### With Label
 
-Add a label above the date range picker using the `label` prop.
+Add a label above the date range picker.
 
 ```tsx
 <DateRangePicker
@@ -90,9 +99,9 @@ Add a label above the date range picker using the `label` prop.
 />
 ```
 
-### Helper Text
+### With Helper Text
 
-Provide additional guidance below the input using the `helperText` prop.
+Provide additional guidance below the input.
 
 ```tsx
 <DateRangePicker
@@ -104,7 +113,7 @@ Provide additional guidance below the input using the `helperText` prop.
 
 ### Error State
 
-Display validation errors by combining the `error` and `helperText` props.
+Show validation errors with error styling.
 
 ```tsx
 <DateRangePicker
@@ -117,7 +126,7 @@ Display validation errors by combining the `error` and `helperText` props.
 
 ### Required Field
 
-Mark the field as required in forms. This displays a required indicator next to the label.
+Mark the field as required in forms.
 
 ```tsx
 <DateRangePicker
@@ -128,11 +137,9 @@ Mark the field as required in forms. This displays a required indicator next to
 />
 ```
 
-## Date Restrictions
-
 ### Minimum Date
 
-Restrict selection to dates on or after a specified minimum date using the `minDate` prop.
+Restrict selection to dates on or after a minimum date.
 
 ```tsx
 <DateRangePicker
@@ -143,7 +150,7 @@ Restrict selection to dates on or after a specified minimum date using the `minD
 
 ### Maximum Date
 
-Restrict selection to dates on or before a specified maximum date using the `maxDate` prop.
+Restrict selection to dates on or before a maximum date.
 
 ```tsx
 <DateRangePicker
@@ -154,7 +161,7 @@ Restrict selection to dates on or before a specified maximum date using the `max
 
 ### Disable Future Dates
 
-Prevent selection of dates in the future using `disableFuture`. Useful for report filters and historical data queries.
+Prevent selection of dates in the future.
 
 ```tsx
 <DateRangePicker
@@ -165,7 +172,7 @@ Prevent selection of dates in the future using `disableFuture`. Useful for repor
 
 ### Disable Past Dates
 
-Prevent selection of dates in the past using `disablePast`. Useful for booking and scheduling forms.
+Prevent selection of dates in the past.
 
 ```tsx
 <DateRangePicker
@@ -174,11 +181,9 @@ Prevent selection of dates in the past using `disablePast`. Useful for booking a
 />
 ```
 
-## Controlled vs Uncontrolled
-
 ### Controlled
 
-In controlled mode, the parent component manages the date range state via `value` and `onChange`. This gives full control over the value, allowing programmatic updates.
+Parent component manages the date range state.
 
 ```tsx
 <Stack gap={2}>
@@ -205,7 +210,7 @@ In controlled mode, the parent component manages the date range state via `value
 
 ### Uncontrolled
 
-In uncontrolled mode, the component manages its own state internally. Set an initial value with `defaultValue` and use `onChange` to react to user selections.
+Component manages its own state internally.
 
 ```tsx
 <DateRangePicker
@@ -216,11 +221,9 @@ In uncontrolled mode, the component manages its own state internally. Set an ini
 />
 ```
 
-## Formatting
+### With Formats
 
-### Value Format (`format`)
-
-The `format` prop controls the format of the value returned in `onChange`. The input always displays in `YYYY/MM/DD` by default, but the `onChange` value follows the specified format.
+Different value formats for the `onChange` event.
 
 ```tsx
 <Stack gap={2}>
@@ -251,9 +254,9 @@ The `format` prop controls the format of the value returned in `onChange`. The i
 </Stack>
 ```
 
-### Display Format (`displayFormat`)
+### With Display Formats
 
-The `displayFormat` prop controls what the user sees in the input field. This is independent of the `format` prop, allowing you to store data in one format while displaying another.
+Different display formats shown in the input field.
 
 ```tsx
 <Stack gap={2}>
@@ -284,38 +287,9 @@ The `displayFormat` prop controls what the user sees in the input field. This is
 </Stack>
 ```
 
-**Supported format tokens:**
-
-| Token  | Description   | Example |
-| ------ | ------------- | ------- |
-| `YYYY` | 4-digit year  | 2024    |
-| `MM`   | 2-digit month | 04      |
-| `DD`   | 2-digit day   | 15      |
-
-```tsx
-// format affects onChange value; displayFormat affects what users see
-<DateRangePicker
-  format="YYYY-MM-DD"        // onChange returns "2024-04-01 - 2024-04-15"
-  displayFormat="MM/DD/YYYY"  // Input shows "04/01/2024 - 04/15/2024"
-/>
-```
-
-## Interaction Modes
-
-### Disabled
-
-Prevent all user interaction when the component is disabled.
-
-```tsx
-<DateRangePicker
-  onChange={onChange}
-  disabled
-/>
-```
-
 ### Input Read Only
 
-Allow calendar selection only while preventing direct typing. Useful on mobile devices where keyboard input is impractical.
+Allow calendar selection only, prevent typing.
 
 ```tsx
 <DateRangePicker
@@ -327,7 +301,7 @@ Allow calendar selection only while preventing direct typing. Useful on mobile d
 
 ### Read Only
 
-Fully read-only state where neither typing nor calendar selection is available. Use this to display a date range value without allowing changes.
+Fully read-only state with no interaction.
 
 ```tsx
 <DateRangePicker
@@ -337,11 +311,9 @@ Fully read-only state where neither typing nor calendar selection is available.
 />
 ```
 
-## Additional Options
-
 ### Hide Clear Button
 
-Remove the clear button from the calendar popup using `hideClearButton`.
+Remove the clear button from the calendar popup.
 
 ```tsx
 <DateRangePicker
@@ -353,7 +325,7 @@ Remove the clear button from the calendar popup using `hideClearButton`.
 
 ### With Reset Button
 
-Example of integrating an external reset button to clear the selected date range programmatically.
+Example with an external reset button.
 
 ```tsx
 <div style={{
@@ -367,6 +339,25 @@ Example of integrating an external reset button to clear the selected date range
 </div>
 ```
 
+## When to Use
+
+### ✅ Good Use Cases
+
+- **Booking systems**: Hotel check-in/out, car rental periods
+- **Report filtering**: Date range filters for analytics and reports
+- **Event scheduling**: Conference dates, project timelines
+- **Leave requests**: Vacation start and end dates
+- **Subscription periods**: Billing cycles, membership durations
+- **Data exports**: Selecting date ranges for exporting data
+
+### ❌ When Not to Use
+
+- **Single date selection**: Use DatePicker instead
+- **Month/Year ranges**: Use MonthRangePicker for month-level granularity
+- **Predefined periods**: For "Last 7 days", "This month", use dropdown selection
+- **Time ranges**: For time-based ranges, use dedicated time components
+- **Recurring dates**: For repeating schedules, consider a custom solution
+
 ## Common Use Cases
 
 ### Booking Form
@@ -376,29 +367,38 @@ function BookingForm() {
   const [dates, setDates] = useState('');
   const [error, setError] = useState('');
 
+  const validateRange = (value) => {
+    if (!value) return 'Please select dates';
+    const [start, end] = value.split(' - ');
+    const startDate = new Date(start);
+    const endDate = new Date(end);
+    const days = (endDate - startDate) / (1000 * 60 * 60 * 24);
+    if (days > 30) return 'Maximum stay is 30 days';
+    if (days < 1) return 'Minimum stay is 1 night';
+    return '';
+  };
+
   const handleChange = (e) => {
     const value = e.target.value;
     setDates(value);
-
-    if (!value) {
-      setError('Please select dates');
-    } else {
-      const [start, end] = value.split(' - ');
-      const days = (new Date(end) - new Date(start)) / (1000 * 60 * 60 * 24);
-      setError(days > 30 ? 'Maximum stay is 30 days' : '');
-    }
+    setError(validateRange(value));
   };
 
   return (
-    <DateRangePicker
-      label="Check-in / Check-out"
-      value={dates}
-      onChange={handleChange}
-      error={!!error}
-      helperText={error || 'Select your stay dates'}
-      disablePast
-      required
-    />
+    <form>
+      <DateRangePicker
+        label="Check-in / Check-out"
+        value={dates}
+        onChange={handleChange}
+        error={!!error}
+        helperText={error || 'Select your stay dates'}
+        disablePast
+        required
+      />
+      <Button type="submit" disabled={!!error || !dates}>
+        Search Availability
+      </Button>
+    </form>
   );
 }
 ```
@@ -421,7 +421,6 @@ function ReportFilters({ onFilter }) {
         label="Report Period"
         value={dateRange}
         onChange={(e) => setDateRange(e.target.value)}
-        format="YYYY-MM-DD"
         disableFuture
         helperText="Select date range for the report"
       />
@@ -431,78 +430,440 @@ function ReportFilters({ onFilter }) {
 }
 ```
 
-### Separate API and Display Formats
+### Leave Request Form
+
+```tsx
+function LeaveRequestForm({ minDate, maxDate }) {
+  const [leaveDates, setLeaveDates] = useState('');
+  const [leaveType, setLeaveType] = useState('annual');
+
+  // Calculate business days
+  const getBusinessDays = (dateRange) => {
+    if (!dateRange) return 0;
+    const [start, end] = dateRange.split(' - ').map(d => new Date(d));
+    let count = 0;
+    const current = new Date(start);
+    while (current <= end) {
+      const day = current.getDay();
+      if (day !== 0 && day !== 6) count++;
+      current.setDate(current.getDate() + 1);
+    }
+    return count;
+  };
+
+  const businessDays = getBusinessDays(leaveDates);
+
+  return (
+    <form>
+      <Select
+        label="Leave Type"
+        value={leaveType}
+        onChange={(e) => setLeaveType(e.target.value)}
+      >
+        <Option value="annual">Annual Leave</Option>
+        <Option value="sick">Sick Leave</Option>
+        <Option value="personal">Personal Leave</Option>
+      </Select>
+
+      <DateRangePicker
+        label="Leave Period"
+        value={leaveDates}
+        onChange={(e) => setLeaveDates(e.target.value)}
+        minDate={minDate}
+        maxDate={maxDate}
+        disablePast
+        helperText={businessDays > 0 ? `${businessDays} business days` : 'Select dates'}
+        required
+      />
+
+      <Button type="submit">Submit Request</Button>
+    </form>
+  );
+}
+```
+
+### Date Range with Presets
+
+```tsx
+function DateRangeWithPresets() {
+  const [dateRange, setDateRange] = useState('');
+
+  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}`;
+  };
+
+  const applyPreset = (preset) => {
+    const today = new Date();
+    let start, end;
+
+    switch (preset) {
+      case 'last7':
+        end = today;
+        start = new Date(today.getTime() - 7 * 24 * 60 * 60 * 1000);
+        break;
+      case 'last30':
+        end = today;
+        start = new Date(today.getTime() - 30 * 24 * 60 * 60 * 1000);
+        break;
+      case 'thisMonth':
+        start = new Date(today.getFullYear(), today.getMonth(), 1);
+        end = new Date(today.getFullYear(), today.getMonth() + 1, 0);
+        break;
+      case 'lastMonth':
+        start = new Date(today.getFullYear(), today.getMonth() - 1, 1);
+        end = new Date(today.getFullYear(), today.getMonth(), 0);
+        break;
+      default:
+        return;
+    }
+
+    setDateRange(`${formatDate(start)} - ${formatDate(end)}`);
+  };
+
+  return (
+    <Stack gap={2}>
+      <Stack direction="row" gap={1}>
+        <Button variant="plain" onClick={() => applyPreset('last7')}>
+          Last 7 Days
+        </Button>
+        <Button variant="plain" onClick={() => applyPreset('last30')}>
+          Last 30 Days
+        </Button>
+        <Button variant="plain" onClick={() => applyPreset('thisMonth')}>
+          This Month
+        </Button>
+        <Button variant="plain" onClick={() => applyPreset('lastMonth')}>
+          Last Month
+        </Button>
+      </Stack>
+      <DateRangePicker
+        label="Custom Range"
+        value={dateRange}
+        onChange={(e) => setDateRange(e.target.value)}
+        disableFuture
+      />
+    </Stack>
+  );
+}
+```
+
+### API Integration
 
 ```tsx
 function DataExport() {
   const [dateRange, setDateRange] = useState('');
+  const [isExporting, setIsExporting] = useState(false);
+
+  const handleExport = async () => {
+    if (!dateRange) return;
+
+    setIsExporting(true);
+    const [startDate, endDate] = dateRange.split(' - ');
+
+    try {
+      const response = await api.exportData({
+        startDate: startDate.replace(/\//g, '-'), // Convert to API format
+        endDate: endDate.replace(/\//g, '-'),
+      });
+      downloadFile(response.data);
+    } finally {
+      setIsExporting(false);
+    }
+  };
 
   return (
-    <DateRangePicker
-      label="Export Period"
-      value={dateRange}
-      onChange={(e) => setDateRange(e.target.value)}
-      format="YYYY-MM-DD"
-      displayFormat="DD/MM/YYYY"
-      disableFuture
-      required
-    />
+    <Stack gap={2}>
+      <DateRangePicker
+        label="Export Period"
+        value={dateRange}
+        onChange={(e) => setDateRange(e.target.value)}
+        format="YYYY/MM/DD"
+        disableFuture
+        required
+      />
+      <Button
+        onClick={handleExport}
+        loading={isExporting}
+        disabled={!dateRange}
+      >
+        Export Data
+      </Button>
+    </Stack>
   );
 }
 ```
 
-## Best Practices
+## Props and Customization
+
+### Key Props
+
+| Prop              | Type                                                        | Default          | Description                                |
+| ----------------- | ----------------------------------------------------------- | ---------------- | ------------------------------------------ |
+| `value`           | `string`                                                    | -                | Controlled value (`"startDate - endDate"`) |
+| `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                     |
+| `inputReadOnly`   | `boolean`                                                   | `false`          | Prevent typing, calendar only              |
+| `readOnly`        | `boolean`                                                   | `false`          | Fully read-only                            |
+| `hideClearButton` | `boolean`                                                   | `false`          | Hide clear button in calendar              |
+
+### Value Format
+
+The value is always a string with start and end dates separated by `-`:
+
+```tsx
+// Value format: "startDate - endDate"
+const value = "2024/04/01 - 2024/04/15";
 
-1. **Match `value` to `format`**: The `value` and `defaultValue` strings must always match the `format` prop. Mismatched formats will cause unexpected behavior.
+// Parsing the value
+const [startDate, endDate] = value.split(' - ');
+console.log(startDate); // "2024/04/01"
+console.log(endDate);   // "2024/04/15"
+```
+
+### Format vs DisplayFormat
 
 ```tsx
-// Correct: value matches format
-<DateRangePicker format="YYYY-MM-DD" value="2024-04-01 - 2024-04-15" />
+// format: Affects the value in onChange
+// displayFormat: Affects what users see in the input
 
-// Incorrect: value does not match format
-<DateRangePicker format="YYYY/MM/DD" value="04/01/2024 - 04/15/2024" />
+<DateRangePicker
+  format="YYYY-MM-DD"       // onChange returns "2024-04-01 - 2024-04-15"
+  displayFormat="MM/DD/YYYY" // Input shows "04/01/2024 - 04/15/2024"
+  onChange={(e) => {
+    console.log(e.target.value); // "2024-04-01 - 2024-04-15"
+  }}
+/>
 ```
 
-2. **Use `displayFormat` to separate concerns**: Store data in an API-friendly format (e.g., `YYYY-MM-DD`) while displaying a user-friendly format (e.g., `MM/DD/YYYY`).
+### Supported Format Tokens
+
+| Token  | Description   | Example |
+| ------ | ------------- | ------- |
+| `YYYY` | 4-digit year  | 2024    |
+| `MM`   | 2-digit month | 04      |
+| `DD`   | 2-digit day   | 15      |
+
+### Controlled vs Uncontrolled
 
 ```tsx
-// Store ISO format, display locale format
+// Uncontrolled - component manages state
 <DateRangePicker
-  format="YYYY-MM-DD"
-  displayFormat="MM/DD/YYYY"
+  defaultValue="2024/04/01 - 2024/04/15"
+  onChange={(e) => console.log(e.target.value)}
+/>
+
+// Controlled - you manage state
+const [dateRange, setDateRange] = useState('2024/04/01 - 2024/04/15');
+<DateRangePicker
+  value={dateRange}
+  onChange={(e) => setDateRange(e.target.value)}
 />
 ```
 
-3. **Use `inputReadOnly` on mobile**: On touch devices, keyboard input for date ranges is error-prone. Use `inputReadOnly` to force calendar selection.
+## Accessibility
+
+DateRangePicker 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
-// Better mobile experience
-<DateRangePicker inputReadOnly />
+// Range selection is announced
+// First click: "Start date: April 1, 2024"
+// Second click: "End date: April 15, 2024"
+
+// Navigation buttons are descriptive
+<button aria-label="Previous Month">←</button>
+<button aria-label="Next Month">→</button>
 ```
 
-4. **Set reasonable date boundaries**: Use `minDate`, `maxDate`, `disablePast`, or `disableFuture` to prevent users from selecting invalid ranges.
+### Focus Management
+
+- Focus moves to calendar when opened
+- Focus returns to input when calendar closes
+- Clear visual focus indicators on all interactive elements
+- Range selection provides visual feedback between start and end dates
+
+## Best Practices
+
+### ✅ Do
+
+1. **Validate date ranges**: Ensure start date is before end date
 
 ```tsx
-// Restrict to a specific period
-<DateRangePicker minDate="2024-01-01" maxDate="2024-12-31" />
+// ✅ Good: Validate the range
+const validateRange = (value) => {
+  const [start, end] = value.split(' - ');
+  if (new Date(start) > new Date(end)) {
+    return 'Start date must be before end date';
+  }
+  return '';
+};
 ```
 
-5. **Display contextual helper text**: Show the duration or additional context in the `helperText` to help users understand their selection.
+2. **Show range duration**: Help users understand the selected period
 
 ```tsx
+// ✅ Good: Display duration
 const getDuration = (value) => {
-  if (!value) return 'Select dates';
-  const [start, end] = value.split(' - ').map((d) => new Date(d));
+  if (!value) return '';
+  const [start, end] = value.split(' - ').map(d => new Date(d));
   const days = Math.ceil((end - start) / (1000 * 60 * 60 * 24));
-  return `${days} day${days !== 1 ? 's' : ''} selected`;
+  return `${days} day${days !== 1 ? 's' : ''}`;
 };
 
-<DateRangePicker helperText={getDuration(dateRange)} />
+<DateRangePicker helperText={getDuration(dateRange) || 'Select dates'} />
 ```
 
-## Accessibility
+3. **Set reasonable limits**: Prevent excessively long ranges
+
+```tsx
+// ✅ Good: Limit range span
+const MAX_DAYS = 90;
+const validateMaxRange = (value) => {
+  const [start, end] = value.split(' - ').map(d => new Date(d));
+  const days = (end - start) / (1000 * 60 * 60 * 24);
+  return days <= MAX_DAYS;
+};
+```
+
+4. **Use consistent formats**: Match your application's locale
+
+```tsx
+// ✅ Good: Consistent with app locale
+<DateRangePicker
+  format="YYYY-MM-DD"  // API format
+  displayFormat="MM/DD/YYYY"  // US locale display
+/>
+```
+
+### ❌ Don't
+
+1. **Don't allow invalid ranges**: Always validate start \< end
+
+```tsx
+// ❌ Bad: No validation
+<DateRangePicker onChange={(e) => setDateRange(e.target.value)} />
+
+// ✅ Good: Validate range
+<DateRangePicker
+  onChange={(e) => {
+    if (isValidRange(e.target.value)) {
+      setDateRange(e.target.value);
+    }
+  }}
+/>
+```
+
+2. **Don't use inconsistent value formats**: Match value to format prop
+
+```tsx
+// ❌ Bad: Mismatched formats
+<DateRangePicker
+  format="YYYY/MM/DD"
+  value="04/01/2024 - 04/15/2024"  // Wrong!
+/>
+
+// ✅ Good: Matching formats
+<DateRangePicker
+  format="YYYY/MM/DD"
+  value="2024/04/01 - 2024/04/15"
+/>
+```
+
+3. **Don't forget mobile users**: Use `inputReadOnly` for better mobile experience
+
+4. **Don't hide important context**: Show duration or business days when relevant
+
+## Performance Considerations
+
+### Memoize Handlers
+
+When using DateRangePicker in complex forms:
+
+```tsx
+const handleChange = useCallback((e) => {
+  setDateRange(e.target.value);
+}, []);
+
+<DateRangePicker value={dateRange} onChange={handleChange} />
+```
+
+### Parse Values Efficiently
+
+When processing date range values:
+
+```tsx
+// Memoize parsed values
+const { startDate, endDate, duration } = useMemo(() => {
+  if (!dateRange) return { startDate: null, endDate: null, duration: 0 };
+
+  const [start, end] = dateRange.split(' - ');
+  const startDate = new Date(start);
+  const endDate = new Date(end);
+  const duration = Math.ceil((endDate - startDate) / (1000 * 60 * 60 * 24));
+
+  return { startDate, endDate, duration };
+}, [dateRange]);
+```
+
+### Format Conversion for APIs
+
+When working with APIs that expect different formats:
+
+```tsx
+function DateRangeField({ value, onChange, apiFormat = 'YYYY-MM-DD' }) {
+  const displayFormat = 'YYYY/MM/DD';
+
+  const convertToDisplay = (apiValue) => {
+    if (!apiValue) return '';
+    const [start, end] = apiValue.split(' - ');
+    return `${convertFormat(start, apiFormat, displayFormat)} - ${convertFormat(end, apiFormat, displayFormat)}`;
+  };
+
+  const convertToApi = (displayValue) => {
+    if (!displayValue) return '';
+    const [start, end] = displayValue.split(' - ');
+    return `${convertFormat(start, displayFormat, apiFormat)} - ${convertFormat(end, displayFormat, apiFormat)}`;
+  };
+
+  return (
+    <DateRangePicker
+      value={convertToDisplay(value)}
+      onChange={(e) => onChange(convertToApi(e.target.value))}
+      format={displayFormat}
+    />
+  );
+}
+```
 
-- The input has `role="textbox"` and the calendar button has `aria-label="Toggle Calendar"` for screen reader identification.
-- **Keyboard navigation** is fully supported: use **Tab** to move between input and calendar button, **Enter/Space** to open the calendar, **Arrow Keys** to navigate dates, and **Escape** to close the popup.
-- When a `label` prop is provided, the input is automatically associated with the label for assistive technologies. Always provide a `label` for form contexts.
-- The calendar popup uses `role="tooltip"` with proper ARIA labeling. Date buttons announce the full date to screen readers, and range selection provides visual feedback between start and end dates.
+DateRangePicker is essential for scenarios requiring start and end date selection. Pay attention to date format consistency, validate ranges properly, and provide clear feedback to users about the selected period.