@ceed/ads 1.23.3 → 1.23.5

package/dist/components/inputs/Calendar.md

@@ -2,7 +2,15 @@
 
 ## Introduction
 
-Calendar is a low-level UI component that renders an interactive calendar grid for date selection. It provides the visual foundation for higher-level picker components like DatePicker, DateRangePicker, and MonthPicker. While you'll rarely use Calendar directly in forms, it's useful for building custom date selection interfaces or embedded calendar views where you need full control over the calendar behavior.
+Calendar is a low-level UI component that renders an interactive calendar grid for date selection. It provides the visual foundation for higher-level picker components like DatePicker, DateRangePicker, and MonthPicker. While you will rarely use Calendar directly in forms, it is useful for building custom date selection interfaces or embedded calendar views where you need full control over the calendar behavior.
+
+Calendar accepts `Date` objects (not strings) and uses an array-based value format `[startDate, endDate]` to support both single-date and range selection modes. It supports multiple locales, view modes (day and month), and flexible date restriction options.
+
+> **Note**: Calendar is a **building block component** intended for custom implementations.
+>
+> - For standard date input, use `DatePicker` instead.
+> - For date ranges, use `DateRangePicker` instead.
+> - For month selection, use `MonthPicker` or `MonthRangePicker`.
 
 ```tsx
 <Calendar />
@@ -12,22 +20,13 @@ Calendar is a low-level UI component that renders an interactive calendar grid f
 | ------ | ----------- | ------- |
 | locale | —           | —       |
 
-> ⚠️ **Usage Warning** ⚠️
->
-> Calendar is a **building block component** intended for custom implementations:
->
-> - **For standard date input**: Use `DatePicker` instead
-> - **For date ranges**: Use `DateRangePicker` instead
-> - **For month selection**: Use `MonthPicker` or `MonthRangePicker`
-> - **Value type**: Calendar uses `Date` objects, not strings like picker components
-> - **No input field**: Calendar is just the grid, with no text input
-
 ## Usage
 
 ```tsx
 import { Calendar } from '@ceed/ads';
+import { useState } from 'react';
 
-function DateViewer() {
+function DateSelector() {
   const [date, setDate] = useState<Date | null>(null);
 
   return (
@@ -39,51 +38,51 @@ function DateViewer() {
 }
 ```
 
-## Examples
-
-### Controlled
+## Controlled
 
-Parent component manages the calendar state.
+In controlled mode, the parent component manages the calendar's selected date via the `value` and `onChange` props. This is the recommended approach for most use cases.
 
 ```tsx
 <Calendar />
 ```
 
-### Uncontrolled
+## Uncontrolled
 
-Calendar manages its own state internally.
+In uncontrolled mode, Calendar manages its own internal state. Use this when you do not need to programmatically read or set the selected date.
 
 ```tsx
 <Calendar />
 ```
 
-### With Locale
+## Locale Support
 
-Display calendar in different languages.
+Display month names, day abbreviations, and first-day-of-week according to a specific locale using the `locale` prop.
 
 ```tsx
 <Calendar locale="de" />
 ```
 
-### Range Selection
+## Range Selection
 
-Enable selection of date ranges (start and end dates).
+Enable `rangeSelection` to allow users to pick a start and end date. The first click sets the start date and the second click sets the end date. Dates between the two are visually highlighted.
 
 ```tsx
 <Calendar rangeSelection />
 ```
 
-### Default Value with Range Selection
+## Default Value with Range Selection
 
-Pre-populate a date range when the calendar loads.
+Pre-populate a date range when the calendar initially renders by providing a `defaultValue` array alongside `rangeSelection`.
 
 ```tsx
 <Calendar rangeSelection defaultValue={[new Date(2024, 2, 1), new Date(2024, 2, 20)]} />
 ```
 
-### Only Month View
+## View Modes
+
+### Month View Only
 
-Show only the month grid without day selection.
+Show only the month grid for month-level navigation and selection.
 
 ```tsx
 <Calendar
@@ -94,7 +93,7 @@ Show only the month grid without day selection.
 
 ### All Views
 
-Show both month and day views with navigation between them.
+Enable both month and day views with navigation between them, giving users the flexibility to zoom in and out of the calendar.
 
 ```tsx
 <Calendar views={['month', 'day']} rangeSelection defaultValue={[new Date(2024, 2, 1), new Date(2024, 2, 20)]} />
@@ -102,15 +101,17 @@ Show both month and day views with navigation between them.
 
 ### Month Selection
 
-Use the calendar for month-level selection only.
+Use the calendar exclusively for selecting a month. Combine `view="month"` with the `onMonthChange` callback to capture month-level changes.
 
 ```tsx
 <Calendar view="month" value={[value, undefined]} onMonthChange={setValue} />
 ```
 
+## 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
 <Calendar minDate={new Date('2024-02-15')} rangeSelection />
@@ -118,7 +119,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
 <Calendar maxDate={new Date('2024-02-15')} rangeSelection />
@@ -126,7 +127,7 @@ Restrict selection to dates on or before a maximum date.
 
 ### Disable Future Dates
 
-Prevent selection of any future dates.
+Prevent selection of any date after today with the `disableFuture` prop.
 
 ```tsx
 <Calendar disableFuture rangeSelection />
@@ -134,7 +135,7 @@ Prevent selection of any future dates.
 
 ### Disable Past Dates
 
-Prevent selection of any past dates.
+Prevent selection of any date before today with the `disablePast` prop.
 
 ```tsx
 <Calendar disablePast rangeSelection />
@@ -142,15 +143,15 @@ Prevent selection of any past dates.
 
 ### Custom Date Disabling
 
-Use `shouldDisableDate` to disable specific dates like weekends.
+Use the `shouldDisableDate` callback to implement arbitrary disabling logic, such as blocking weekends.
 
 ```tsx
 <Calendar shouldDisableDate={date => [0, 6].includes(date.getDay())} />
 ```
 
-### Weekends Disabled with Past Dates
+### Weekends and Past Dates Disabled
 
-Combine multiple restrictions: disable weekends and past dates.
+Combine `shouldDisableDate` with `disablePast` to apply multiple restrictions simultaneously.
 
 ```tsx
 <Calendar shouldDisableDate={date => [0, 6].includes(date.getDay())} disablePast />
@@ -158,49 +159,33 @@ Combine multiple restrictions: disable weekends and past dates.
 
 ### Complex Date Restrictions
 
-Disable weekends, past dates, and limit to one week ahead.
+Disable weekends, past dates, and limit selection to one week ahead by combining all restriction options.
 
 ```tsx
 <Calendar shouldDisableDate={date => [0, 6].includes(date.getDay()) || date.getTime() >= new Date().getTime() + 7 * 24 * 60 * 60 * 1000} disablePast />
 ```
 
-## When to Use
-
-### ✅ Good Use Cases
-
-- **Custom date picker UI**: Building a specialized date selection interface
-- **Embedded calendar**: Showing a calendar inline within a page layout
-- **Dashboard widget**: Calendar as a date navigation widget
-- **Event calendar**: Base for event/appointment calendars
-- **Custom range pickers**: Building specialized range selection UI
-- **Full control needed**: When you need direct access to calendar behavior
-
-### ❌ When Not to Use
-
-- **Form date input**: Use `DatePicker` for standard form fields
-- **Date range forms**: Use `DateRangePicker` for start/end date pairs
-- **Month selection forms**: Use `MonthPicker` or `MonthRangePicker`
-- **Simple date display**: Use a text display or formatted date
-- **Date with time**: Calendar doesn't include time selection
-
 ## Common Use Cases
 
 ### Embedded Calendar Widget
 
 ```tsx
+import { Calendar } from '@ceed/ads';
+import { Box, Typography } from '@ceed/ads';
+
 function CalendarWidget() {
   const [selectedDate, setSelectedDate] = useState<Date>(new Date());
 
   return (
     <Box sx={{ p: 2, border: '1px solid', borderColor: 'divider', borderRadius: 'md' }}>
-      <Typography level="title-md" mb={2}>
+      <Typography level="title-md" sx={{ mb: 2 }}>
         Select a Date
       </Typography>
       <Calendar
         value={[selectedDate, undefined]}
         onChange={(dates) => dates[0] && setSelectedDate(dates[0])}
       />
-      <Typography level="body-sm" mt={2}>
+      <Typography level="body-sm" sx={{ mt: 2 }}>
         Selected: {selectedDate.toLocaleDateString()}
       </Typography>
     </Box>
@@ -208,111 +193,38 @@ function CalendarWidget() {
 }
 ```
 
-### Event Calendar with Highlighted Dates
+### Booking Calendar with Disabled Dates
 
 ```tsx
-function EventCalendar({ events }) {
-  const [viewDate, setViewDate] = useState<Date>(new Date());
-
-  // Get dates with events
-  const eventDates = useMemo(() => {
-    return events.map((e) => e.date.toDateString());
-  }, [events]);
-
-  const hasEvent = (date: Date) => eventDates.includes(date.toDateString());
-
-  return (
-    <Stack gap={2}>
-      <Calendar
-        value={[viewDate, undefined]}
-        onChange={(dates) => dates[0] && setViewDate(dates[0])}
-      />
-      {hasEvent(viewDate) && (
-        <Box>
-          <Typography level="title-sm">Events on {viewDate.toLocaleDateString()}</Typography>
-          {events
-            .filter((e) => e.date.toDateString() === viewDate.toDateString())
-            .map((event) => (
-              <Typography key={event.id} level="body-sm">
-                {event.title}
-              </Typography>
-            ))}
-        </Box>
-      )}
-    </Stack>
-  );
-}
-```
-
-### Appointment Booking Calendar
-
-```tsx
-function BookingCalendar({ availableSlots, onBook }) {
+function BookingCalendar({ blockedDates }) {
   const [selectedDate, setSelectedDate] = useState<Date | null>(null);
 
-  // Get available dates
-  const availableDates = useMemo(() => {
-    return new Set(availableSlots.map((slot) => slot.date.toDateString()));
-  }, [availableSlots]);
-
-  // Disable dates without available slots
-  const shouldDisableDate = (date: Date) => {
-    const isPast = date < new Date(new Date().setHours(0, 0, 0, 0));
-    const hasNoSlots = !availableDates.has(date.toDateString());
-    return isPast || hasNoSlots;
-  };
-
-  const slotsForSelectedDate = useMemo(() => {
-    if (!selectedDate) return [];
-    return availableSlots.filter(
-      (slot) => slot.date.toDateString() === selectedDate.toDateString()
-    );
-  }, [selectedDate, availableSlots]);
+  const blockedSet = useMemo(
+    () => new Set(blockedDates.map((d) => d.toDateString())),
+    [blockedDates]
+  );
 
   return (
-    <Stack direction="row" gap={3}>
-      <Calendar
-        value={selectedDate ? [selectedDate, undefined] : undefined}
-        onChange={(dates) => setSelectedDate(dates[0] || null)}
-        shouldDisableDate={shouldDisableDate}
-        disablePast
-      />
-      {selectedDate && (
-        <Box sx={{ minWidth: 200 }}>
-          <Typography level="title-sm" mb={1}>
-            Available Times on {selectedDate.toLocaleDateString()}
-          </Typography>
-          <Stack gap={1}>
-            {slotsForSelectedDate.map((slot) => (
-              <Button
-                key={slot.id}
-                variant="outlined"
-                size="sm"
-                onClick={() => onBook(slot)}
-              >
-                {slot.time}
-              </Button>
-            ))}
-          </Stack>
-        </Box>
-      )}
-    </Stack>
+    <Calendar
+      value={selectedDate ? [selectedDate, undefined] : undefined}
+      onChange={(dates) => setSelectedDate(dates[0] || null)}
+      disablePast
+      shouldDisableDate={(date) =>
+        [0, 6].includes(date.getDay()) || blockedSet.has(date.toDateString())
+      }
+    />
   );
 }
 ```
 
-### Date Range Selection with Preview
+### Date Range Selector with Summary
 
 ```tsx
 function DateRangeSelector({ onRangeSelect }) {
-  const [range, setRange] = useState<[Date | undefined, Date | undefined]>([undefined, undefined]);
-
-  const handleChange = (dates: [Date | undefined, Date | undefined]) => {
-    setRange(dates);
-    if (dates[0] && dates[1]) {
-      onRangeSelect({ start: dates[0], end: dates[1] });
-    }
-  };
+  const [range, setRange] = useState<[Date | undefined, Date | undefined]>([
+    undefined,
+    undefined,
+  ]);
 
   const dayCount = useMemo(() => {
     if (!range[0] || !range[1]) return 0;
@@ -325,349 +237,76 @@ function DateRangeSelector({ onRangeSelect }) {
       <Calendar
         rangeSelection
         value={range}
-        onChange={handleChange}
+        onChange={(dates) => {
+          setRange(dates);
+          if (dates[0] && dates[1]) onRangeSelect(dates);
+        }}
         disablePast
       />
-      <Box>
-        {range[0] && (
-          <Typography level="body-sm">
-            Start: {range[0].toLocaleDateString()}
-          </Typography>
-        )}
-        {range[1] && (
-          <Typography level="body-sm">
-            End: {range[1].toLocaleDateString()} ({dayCount} days)
-          </Typography>
-        )}
-        {!range[0] && (
-          <Typography level="body-sm" color="neutral">
-            Select start date
-          </Typography>
-        )}
-      </Box>
+      {range[0] && range[1] && (
+        <Typography level="body-sm">
+          {range[0].toLocaleDateString()} - {range[1].toLocaleDateString()} ({dayCount} days)
+        </Typography>
+      )}
     </Stack>
   );
 }
 ```
 
-### Multi-Language Calendar
-
-```tsx
-function LocalizedCalendar({ userLocale }) {
-  const [date, setDate] = useState<Date>(new Date());
-
-  // Map common locales
-  const getCalendarLocale = (locale: string) => {
-    const localeMap: Record<string, string> = {
-      'en-US': 'en',
-      'ko-KR': 'ko',
-      'ja-JP': 'ja',
-      'de-DE': 'de',
-      'fr-FR': 'fr',
-      'zh-CN': 'zh',
-    };
-    return localeMap[locale] || 'en';
-  };
-
-  return (
-    <Calendar
-      value={[date, undefined]}
-      onChange={(dates) => dates[0] && setDate(dates[0])}
-      locale={getCalendarLocale(userLocale)}
-    />
-  );
-}
-```
-
-### Month Navigation Widget
-
-```tsx
-function MonthNavigator({ onMonthChange }) {
-  const [currentMonth, setCurrentMonth] = useState<Date>(new Date());
-
-  const handleMonthChange = (date: Date) => {
-    setCurrentMonth(date);
-    onMonthChange(date);
-  };
-
-  return (
-    <Box>
-      <Typography level="title-md" mb={2}>
-        {currentMonth.toLocaleDateString('en-US', { month: 'long', year: 'numeric' })}
-      </Typography>
-      <Calendar
-        view="month"
-        views={['month']}
-        value={[currentMonth, undefined]}
-        onMonthChange={handleMonthChange}
-      />
-    </Box>
-  );
-}
-```
-
-## Props and Customization
-
-### Key Props
-
-| Prop                | Type                                                      | Default   | Description                                      |
-| ------------------- | --------------------------------------------------------- | --------- | ------------------------------------------------ |
-| `value`             | `[Date \| undefined, Date \| undefined]`                  | -         | Controlled value as array `[startDate, endDate]` |
-| `defaultValue`      | `[Date \| undefined, Date \| undefined]`                  | -         | Default value for uncontrolled mode              |
-| `onChange`          | `(dates: [Date \| undefined, Date \| undefined]) => void` | -         | Change handler                                   |
-| `rangeSelection`    | `boolean`                                                 | `false`   | Enable date range selection mode                 |
-| `view`              | `'day' \| 'month'`                                        | `'day'`   | Current view mode                                |
-| `views`             | `('day' \| 'month')[]`                                    | `['day']` | Available views for navigation                   |
-| `locale`            | `string`                                                  | `'en'`    | Locale for month/day names                       |
-| `minDate`           | `Date`                                                    | -         | Minimum selectable date                          |
-| `maxDate`           | `Date`                                                    | -         | Maximum selectable date                          |
-| `disableFuture`     | `boolean`                                                 | `false`   | Disable all future dates                         |
-| `disablePast`       | `boolean`                                                 | `false`   | Disable all past dates                           |
-| `shouldDisableDate` | `(date: Date) => boolean`                                 | -         | Custom function to disable specific dates        |
-| `onMonthChange`     | `(date: Date) => void`                                    | -         | Callback when month changes                      |
-
-### Value Format
-
-Calendar uses `Date` objects instead of strings:
-
-```tsx
-// Single date selection (use undefined for second element)
-<Calendar
-  value={[new Date('2024-04-15'), undefined]}
-  onChange={(dates) => console.log(dates[0])} // Date object
-/>
-
-// Range selection
-<Calendar
-  rangeSelection
-  value={[new Date('2024-04-01'), new Date('2024-04-15')]}
-  onChange={(dates) => {
-    const [start, end] = dates;
-    console.log('Start:', start); // Date object
-    console.log('End:', end);     // Date object
-  }}
-/>
-```
-
-### View Modes
-
-```tsx
-// Day view only (default)
-<Calendar views={['day']} />
-
-// Month view only
-<Calendar views={['month']} view="month" />
-
-// Both views with navigation
-<Calendar views={['month', 'day']} />
-```
-
-### Date Restrictions
-
-```tsx
-// Restrict to specific range
-<Calendar
-  minDate={new Date('2024-01-01')}
-  maxDate={new Date('2024-12-31')}
-/>
-
-// Disable weekends
-<Calendar
-  shouldDisableDate={(date) => [0, 6].includes(date.getDay())}
-/>
-
-// Combine multiple restrictions
-<Calendar
-  disablePast
-  disableFuture={false}
-  maxDate={new Date(Date.now() + 30 * 24 * 60 * 60 * 1000)} // 30 days ahead
-  shouldDisableDate={(date) => [0, 6].includes(date.getDay())}
-/>
-```
-
-## Accessibility
-
-Calendar includes built-in accessibility features:
-
-### ARIA Attributes
-
-- Calendar uses proper grid roles for navigation
-- Days are announced with full date context
-- Disabled dates are marked as `aria-disabled`
-- Selected dates use `aria-selected`
-
-### Keyboard Navigation
-
-- **Arrow Keys**: Navigate between days
-- **Page Up/Down**: Navigate between months
-- **Home/End**: Jump to start/end of week
-- **Enter/Space**: Select focused date
-- **Tab**: Move focus to calendar navigation buttons
-
-### Screen Reader Support
-
-```tsx
-// Days are announced with full context
-<button aria-label="April 15, 2024">15</button>
-
-// Month navigation buttons are descriptive
-<button aria-label="Previous Month">←</button>
-<button aria-label="Next Month">→</button>
-
-// Disabled dates are announced
-<button aria-label="April 20, 2024 (unavailable)" aria-disabled="true">20</button>
-```
-
-### Focus Management
-
-- Focus remains within calendar during navigation
-- Visual focus indicator on active day
-- Disabled dates are not focusable
-
 ## Best Practices
 
-### ✅ Do
-
-1. **Use appropriate picker components for forms**: Default to DatePicker/DateRangePicker
+1. **Prefer higher-level picker components for form fields.** Use DatePicker or DateRangePicker unless you need a custom embedded calendar UI.
 
 ```tsx
-// ✅ Good: Use DatePicker for form input
-<DatePicker
-  label="Birth Date"
-  value={date}
-  onChange={(e) => setDate(e.target.value)}
-/>
-```
-
-2. **Provide clear context when using Calendar directly**: Add surrounding UI to explain the calendar's purpose
-
-```tsx
-// ✅ Good: Clear context around calendar
-<Box>
-  <Typography level="title-md">Select Appointment Date</Typography>
-  <Calendar value={[date, undefined]} onChange={handleChange} />
-  <Typography level="body-sm">Selected: {date?.toLocaleDateString()}</Typography>
-</Box>
-```
+// ✅ Use DatePicker for standard form input
+<DatePicker label="Birth Date" value={date} onChange={handleChange} />
 
-3. **Use appropriate date restrictions**: Prevent invalid selections
-
-```tsx
-// ✅ Good: Reasonable constraints for booking
-<Calendar
-  disablePast
-  maxDate={new Date(Date.now() + 90 * 24 * 60 * 60 * 1000)} // 90 days ahead
-  shouldDisableDate={(date) => [0, 6].includes(date.getDay())} // No weekends
-/>
+// ❌ Using Calendar directly in a form without context
+<form>
+  <Calendar onChange={handleChange} />
+</form>
 ```
 
-4. **Handle the array value format correctly**: Calendar always uses `[start, end]` format
+2. **Handle the array value format correctly.** Calendar always uses `[start, end]` format, even for single date selection.
 
 ```tsx
-// ✅ Good: Proper value handling
-const [date, setDate] = useState<Date | null>(null);
+// ✅ Proper single-date handling
 <Calendar
   value={date ? [date, undefined] : undefined}
   onChange={(dates) => setDate(dates[0] || null)}
 />
-```
-
-### ❌ Don't
-
-1. **Don't use Calendar when DatePicker suffices**: For standard form inputs, use the picker components
-
-```tsx
-// ❌ Bad: Using Calendar for simple date input
-<form>
-  <Calendar onChange={handleChange} /> {/* Missing label, not form-friendly */}
-</form>
-
-// ✅ Good: Use DatePicker
-<DatePicker label="Date" value={value} onChange={handleChange} />
-```
 
-2. **Don't forget to handle both elements of the array**: Even for single selection
-
-```tsx
-// ❌ Bad: Ignoring array format
-<Calendar onChange={(date) => setDate(date)} />
-
-// ✅ Good: Proper array handling
-<Calendar onChange={(dates) => setDate(dates[0])} />
+// ❌ Treating value as a single Date
+<Calendar value={date} onChange={(d) => setDate(d)} />
 ```
 
-3. **Don't mix Date objects with string values**: Calendar uses Date objects
-
-```tsx
-// ❌ Bad: Using string values
-<Calendar value={["2024-04-15", undefined]} />
-
-// ✅ Good: Using Date objects
-<Calendar value={[new Date("2024-04-15"), undefined]} />
-```
-
-4. **Don't forget locale for international users**: Set appropriate locale
-
-## Performance Considerations
-
-### Memoize shouldDisableDate
-
-For complex date validation, memoize the function:
+3. **Memoize `shouldDisableDate` for performance.** Complex date validation logic runs on every date cell render, so use `useCallback` or `useMemo` to prevent unnecessary recalculations.
 
 ```tsx
+// ✅ Memoized disable function
 const shouldDisableDate = useCallback((date: Date) => {
-  // Check if weekend
-  if ([0, 6].includes(date.getDay())) return true;
-
-  // Check against holiday list
-  const dateString = date.toISOString().split('T')[0];
-  return holidays.includes(dateString);
-}, [holidays]); // Only recreate when holidays change
+  return [0, 6].includes(date.getDay()) || holidays.has(date.toDateString());
+}, [holidays]);
 
-<Calendar shouldDisableDate={shouldDisableDate} />
+// ❌ Inline function recreated every render
+<Calendar shouldDisableDate={(date) => expensiveCheck(date)} />
 ```
 
-### Avoid Inline Object Creation
-
-When using controlled mode, avoid creating new arrays on every render:
+4. **Always use Date objects, not strings.** Calendar expects native `Date` objects for `value`, `defaultValue`, `minDate`, and `maxDate`.
 
 ```tsx
-// ❌ Bad: New array on every render
-<Calendar value={[date, undefined]} />
-
-// ✅ Good: Memoize the value
-const calendarValue = useMemo(
-  () => (date ? [date, undefined] : undefined),
-  [date]
-);
-<Calendar value={calendarValue} />
-```
-
-### Optimize Event Handlers
+// ✅ Using Date objects
+<Calendar value={[new Date('2024-04-15'), undefined]} />
 
-```tsx
-const handleChange = useCallback((dates: [Date | undefined, Date | undefined]) => {
-  setSelectedDate(dates[0] || null);
-}, []);
-
-<Calendar onChange={handleChange} />
+// ❌ Using string values
+<Calendar value={['2024-04-15', undefined]} />
 ```
 
-### Lazy Date Calculations
-
-For complex availability calculations:
+5. **Provide surrounding context when using Calendar directly.** Add a heading or label to explain the calendar's purpose, since Calendar itself has no built-in label.
 
-```tsx
-const disabledDates = useMemo(() => {
-  // Pre-calculate disabled dates once
-  return new Set(
-    blockedDates.map((d) => d.toDateString())
-  );
-}, [blockedDates]);
-
-const shouldDisableDate = useCallback((date: Date) => {
-  return disabledDates.has(date.toDateString());
-}, [disabledDates]);
-```
+## Accessibility
 
-Calendar is a foundational component for building custom date selection interfaces. For most use cases, prefer the higher-level picker components (DatePicker, DateRangePicker, MonthPicker) which provide built-in form integration, labels, and text input. Use Calendar directly when you need full control over the calendar UI or are building specialized date-related features.
+- **Keyboard navigation**: Arrow keys navigate between days, Page Up/Down switches months, Home/End jumps to start/end of the week, and Enter/Space selects the focused date.
+- **ARIA attributes**: Days are announced with full date context. Selected dates use `aria-selected` and disabled dates are marked with `aria-disabled`.
+- **Focus management**: Focus remains within the calendar during navigation. Disabled dates are skipped during keyboard traversal.
+- **Screen reader support**: Month navigation buttons include descriptive labels (e.g., "Previous Month", "Next Month"), and each day cell is announced with its full date.