@ceed/cds 1.24.1-next.3 → 1.26.0

package/dist/components/inputs/DateRangePicker.md

@@ -2,7 +2,9 @@
 
 ## 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 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.
+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.
 
 ```tsx
 <DateRangePicker onChange={onChange} />
@@ -28,14 +30,22 @@ DateRangePicker is a form input component that allows users to select a date ran
 | hideClearButton | —           | —       |
 | size            | —           | —       |
 
-> ⚠️ **Usage Warning** ⚠️
+> **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.
 >
-> DateRangePicker involves complex date range handling:
+> ```tsx
+> // Recommended: use built-in props
+> <DateRangePicker label="Period" helperText="Select start and end dates" />
 >
-> - **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
+> // 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>
+> ```
 
 ## Usage
 
@@ -55,19 +65,9 @@ function DateRangeForm() {
 }
 ```
 
-## Examples
+## Sizes
 
-### Playground
-
-Interactive example with all controls.
-
-```tsx
-<DateRangePicker onChange={onChange} />
-```
-
-### Sizes
-
-DateRangePicker supports three sizes for different layouts.
+DateRangePicker supports three sizes (`sm`, `md`, `lg`) to fit different layouts and density requirements.
 
 ```tsx
 <Stack gap={2}>
@@ -77,20 +77,11 @@ DateRangePicker supports three sizes for different layouts.
 </Stack>
 ```
 
-### Disabled
-
-Prevent user interaction when disabled.
-
-```tsx
-<DateRangePicker
-  onChange={onChange}
-  disabled
-/>
-```
+## Form Features
 
-### With Label
+### Label
 
-Add a label above the date range picker.
+Add a label above the date range picker using the `label` prop.
 
 ```tsx
 <DateRangePicker
@@ -99,9 +90,9 @@ Add a label above the date range picker.
 />
 ```
 
-### With Helper Text
+### Helper Text
 
-Provide additional guidance below the input.
+Provide additional guidance below the input using the `helperText` prop.
 
 ```tsx
 <DateRangePicker
@@ -113,7 +104,7 @@ Provide additional guidance below the input.
 
 ### Error State
 
-Show validation errors with error styling.
+Display validation errors by combining the `error` and `helperText` props.
 
 ```tsx
 <DateRangePicker
@@ -126,7 +117,7 @@ Show validation errors with error styling.
 
 ### Required Field
 
-Mark the field as required in forms.
+Mark the field as required in forms. This displays a required indicator next to the label.
 
 ```tsx
 <DateRangePicker
@@ -137,9 +128,11 @@ Mark the field as required in forms.
 />
 ```
 
+## Date Restrictions
+
 ### Minimum Date
 
-Restrict selection to dates on or after a minimum date.
+Restrict selection to dates on or after a specified minimum date using the `minDate` prop.
 
 ```tsx
 <DateRangePicker
@@ -150,7 +143,7 @@ Restrict selection to dates on or after a minimum date.
 
 ### Maximum Date
 
-Restrict selection to dates on or before a maximum date.
+Restrict selection to dates on or before a specified maximum date using the `maxDate` prop.
 
 ```tsx
 <DateRangePicker
@@ -161,7 +154,7 @@ Restrict selection to dates on or before a maximum date.
 
 ### Disable Future Dates
 
-Prevent selection of dates in the future.
+Prevent selection of dates in the future using `disableFuture`. Useful for report filters and historical data queries.
 
 ```tsx
 <DateRangePicker
@@ -172,7 +165,7 @@ Prevent selection of dates in the future.
 
 ### Disable Past Dates
 
-Prevent selection of dates in the past.
+Prevent selection of dates in the past using `disablePast`. Useful for booking and scheduling forms.
 
 ```tsx
 <DateRangePicker
@@ -181,9 +174,11 @@ Prevent selection of dates in the past.
 />
 ```
 
+## Controlled vs Uncontrolled
+
 ### Controlled
 
-Parent component manages the date range state.
+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.
 
 ```tsx
 <Stack gap={2}>
@@ -210,7 +205,7 @@ Parent component manages the date range state.
 
 ### Uncontrolled
 
-Component manages its own state internally.
+In uncontrolled mode, the component manages its own state internally. Set an initial value with `defaultValue` and use `onChange` to react to user selections.
 
 ```tsx
 <DateRangePicker
@@ -221,9 +216,11 @@ Component manages its own state internally.
 />
 ```
 
-### With Formats
+## Formatting
 
-Different value formats for the `onChange` event.
+### 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.
 
 ```tsx
 <Stack gap={2}>
@@ -254,9 +251,9 @@ Different value formats for the `onChange` event.
 </Stack>
 ```
 
-### With Display Formats
+### Display Format (`displayFormat`)
 
-Different display formats shown in the input field.
+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.
 
 ```tsx
 <Stack gap={2}>
@@ -287,9 +284,38 @@ Different display formats shown in the input field.
 </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, prevent typing.
+Allow calendar selection only while preventing direct typing. Useful on mobile devices where keyboard input is impractical.
 
 ```tsx
 <DateRangePicker
@@ -301,7 +327,7 @@ Allow calendar selection only, prevent typing.
 
 ### Read Only
 
-Fully read-only state with no interaction.
+Fully read-only state where neither typing nor calendar selection is available. Use this to display a date range value without allowing changes.
 
 ```tsx
 <DateRangePicker
@@ -311,9 +337,11 @@ Fully read-only state with no interaction.
 />
 ```
 
+## Additional Options
+
 ### Hide Clear Button
 
-Remove the clear button from the calendar popup.
+Remove the clear button from the calendar popup using `hideClearButton`.
 
 ```tsx
 <DateRangePicker
@@ -325,7 +353,7 @@ Remove the clear button from the calendar popup.
 
 ### With Reset Button
 
-Example with an external reset button.
+Example of integrating an external reset button to clear the selected date range programmatically.
 
 ```tsx
 <div style={{
@@ -339,25 +367,6 @@ Example with an external reset button.
 </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
@@ -367,38 +376,29 @@ 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);
-    setError(validateRange(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' : '');
+    }
   };
 
   return (
-    <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>
+    <DateRangePicker
+      label="Check-in / Check-out"
+      value={dates}
+      onChange={handleChange}
+      error={!!error}
+      helperText={error || 'Select your stay dates'}
+      disablePast
+      required
+    />
   );
 }
 ```
@@ -421,6 +421,7 @@ 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"
       />
@@ -430,440 +431,78 @@ function ReportFilters({ onFilter }) {
 }
 ```
 
-### 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
+### Separate API and Display Formats
 
 ```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 (
-    <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>
+    <DateRangePicker
+      label="Export Period"
+      value={dateRange}
+      onChange={(e) => setDateRange(e.target.value)}
+      format="YYYY-MM-DD"
+      displayFormat="DD/MM/YYYY"
+      disableFuture
+      required
+    />
   );
 }
 ```
 
-## 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";
-
-// Parsing the value
-const [startDate, endDate] = value.split(' - ');
-console.log(startDate); // "2024/04/01"
-console.log(endDate);   // "2024/04/15"
-```
+## Best Practices
 
-### Format vs DisplayFormat
+1. **Match `value` to `format`**: The `value` and `defaultValue` strings must always match the `format` prop. Mismatched formats will cause unexpected behavior.
 
 ```tsx
-// format: Affects the value in onChange
-// displayFormat: Affects what users see in the input
+// Correct: value matches format
+<DateRangePicker format="YYYY-MM-DD" value="2024-04-01 - 2024-04-15" />
 
-<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"
-  }}
-/>
+// Incorrect: value does not match format
+<DateRangePicker format="YYYY/MM/DD" value="04/01/2024 - 04/15/2024" />
 ```
 
-### Supported Format Tokens
-
-| Token  | Description   | Example |
-| ------ | ------------- | ------- |
-| `YYYY` | 4-digit year  | 2024    |
-| `MM`   | 2-digit month | 04      |
-| `DD`   | 2-digit day   | 15      |
-
-### Controlled vs Uncontrolled
+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`).
 
 ```tsx
-// Uncontrolled - component manages state
+// Store ISO format, display locale format
 <DateRangePicker
-  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)}
+  format="YYYY-MM-DD"
+  displayFormat="MM/DD/YYYY"
 />
 ```
 
-## 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
+3. **Use `inputReadOnly` on mobile**: On touch devices, keyboard input for date ranges is error-prone. Use `inputReadOnly` to force calendar selection.
 
 ```tsx
-// 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>
+// Better mobile experience
+<DateRangePicker inputReadOnly />
 ```
 
-### 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
+4. **Set reasonable date boundaries**: Use `minDate`, `maxDate`, `disablePast`, or `disableFuture` to prevent users from selecting invalid ranges.
 
 ```tsx
-// ✅ 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 '';
-};
+// Restrict to a specific period
+<DateRangePicker minDate="2024-01-01" maxDate="2024-12-31" />
 ```
 
-2. **Show range duration**: Help users understand the selected period
+5. **Display contextual helper text**: Show the duration or additional context in the `helperText` to help users understand their selection.
 
 ```tsx
-// ✅ Good: Display duration
 const getDuration = (value) => {
-  if (!value) return '';
-  const [start, end] = value.split(' - ').map(d => new Date(d));
+  if (!value) return 'Select dates';
+  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' : ''}`;
+  return `${days} day${days !== 1 ? 's' : ''} selected`;
 };
 
-<DateRangePicker helperText={getDuration(dateRange) || 'Select dates'} />
-```
-
-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;
-};
+<DateRangePicker helperText={getDuration(dateRange)} />
 ```
 
-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}
-    />
-  );
-}
-```
+## Accessibility
 
-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.
+- 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.