@ceed/ads 1.29.1 → 1.30.0-next.1

package/dist/components/inputs/Calendar.md

@@ -2,15 +2,7 @@
 
 ## 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 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`.
+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.
 
 ```tsx
 <Calendar />
@@ -20,13 +12,22 @@ Calendar accepts `Date` objects (not strings) and uses an array-based value form
 | ------ | ----------- | ------- |
 | 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 DateSelector() {
+function DateViewer() {
   const [date, setDate] = useState<Date | null>(null);
 
   return (
@@ -38,51 +39,51 @@ function DateSelector() {
 }
 ```
 
-## Controlled
+## Examples
+
+### Controlled
 
-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.
+Parent component manages the calendar state.
 
 ```tsx
 <Calendar />
 ```
 
-## Uncontrolled
+### Uncontrolled
 
-In uncontrolled mode, Calendar manages its own internal state. Use this when you do not need to programmatically read or set the selected date.
+Calendar manages its own state internally.
 
 ```tsx
 <Calendar />
 ```
 
-## Locale Support
+### With Locale
 
-Display month names, day abbreviations, and first-day-of-week according to a specific locale using the `locale` prop.
+Display calendar in different languages.
 
 ```tsx
 <Calendar locale="de" />
 ```
 
-## Range Selection
+### Range Selection
 
-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.
+Enable selection of date ranges (start and end dates).
 
 ```tsx
 <Calendar rangeSelection />
 ```
 
-## Default Value with Range Selection
+### Default Value with Range Selection
 
-Pre-populate a date range when the calendar initially renders by providing a `defaultValue` array alongside `rangeSelection`.
+Pre-populate a date range when the calendar loads.
 
 ```tsx
 <Calendar rangeSelection defaultValue={[new Date(2024, 2, 1), new Date(2024, 2, 20)]} />
 ```
 
-## View Modes
-
-### Month View Only
+### Only Month View
 
-Show only the month grid for month-level navigation and selection.
+Show only the month grid without day selection.
 
 ```tsx
 <Calendar
@@ -93,7 +94,7 @@ Show only the month grid for month-level navigation and selection.
 
 ### All Views
 
-Enable both month and day views with navigation between them, giving users the flexibility to zoom in and out of the calendar.
+Show both month and day views with navigation between them.
 
 ```tsx
 <Calendar views={['month', 'day']} rangeSelection defaultValue={[new Date(2024, 2, 1), new Date(2024, 2, 20)]} />
@@ -101,17 +102,15 @@ Enable both month and day views with navigation between them, giving users the f
 
 ### Month Selection
 
-Use the calendar exclusively for selecting a month. Combine `view="month"` with the `onMonthChange` callback to capture month-level changes.
+Use the calendar for month-level selection only.
 
 ```tsx
 <Calendar view="month" value={[value, undefined]} onMonthChange={setValue} />
 ```
 
-## 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
 <Calendar minDate={new Date('2024-02-15')} rangeSelection />
@@ -119,7 +118,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
 <Calendar maxDate={new Date('2024-02-15')} rangeSelection />
@@ -127,7 +126,7 @@ Restrict selection to dates on or before a specified maximum date using the `max
 
 ### Disable Future Dates
 
-Prevent selection of any date after today with the `disableFuture` prop.
+Prevent selection of any future dates.
 
 ```tsx
 <Calendar disableFuture rangeSelection />
@@ -135,7 +134,7 @@ Prevent selection of any date after today with the `disableFuture` prop.
 
 ### Disable Past Dates
 
-Prevent selection of any date before today with the `disablePast` prop.
+Prevent selection of any past dates.
 
 ```tsx
 <Calendar disablePast rangeSelection />
@@ -143,15 +142,15 @@ Prevent selection of any date before today with the `disablePast` prop.
 
 ### Custom Date Disabling
 
-Use the `shouldDisableDate` callback to implement arbitrary disabling logic, such as blocking weekends.
+Use `shouldDisableDate` to disable specific dates like weekends.
 
 ```tsx
 <Calendar shouldDisableDate={date => [0, 6].includes(date.getDay())} />
 ```
 
-### Weekends and Past Dates Disabled
+### Weekends Disabled with Past Dates
 
-Combine `shouldDisableDate` with `disablePast` to apply multiple restrictions simultaneously.
+Combine multiple restrictions: disable weekends and past dates.
 
 ```tsx
 <Calendar shouldDisableDate={date => [0, 6].includes(date.getDay())} disablePast />
@@ -159,33 +158,49 @@ Combine `shouldDisableDate` with `disablePast` to apply multiple restrictions si
 
 ### Complex Date Restrictions
 
-Disable weekends, past dates, and limit selection to one week ahead by combining all restriction options.
+Disable weekends, past dates, and limit to one week ahead.
 
 ```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" sx={{ mb: 2 }}>
+      <Typography level="title-md" mb={2}>
         Select a Date
       </Typography>
       <Calendar
         value={[selectedDate, undefined]}
         onChange={(dates) => dates[0] && setSelectedDate(dates[0])}
       />
-      <Typography level="body-sm" sx={{ mt: 2 }}>
+      <Typography level="body-sm" mt={2}>
         Selected: {selectedDate.toLocaleDateString()}
       </Typography>
     </Box>
@@ -193,38 +208,111 @@ function CalendarWidget() {
 }
 ```
 
-### Booking Calendar with Disabled Dates
+### Event Calendar with Highlighted Dates
 
 ```tsx
-function BookingCalendar({ blockedDates }) {
-  const [selectedDate, setSelectedDate] = useState<Date | null>(null);
+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 blockedSet = useMemo(
-    () => new Set(blockedDates.map((d) => d.toDateString())),
-    [blockedDates]
+  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 }) {
+  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]);
 
   return (
-    <Calendar
-      value={selectedDate ? [selectedDate, undefined] : undefined}
-      onChange={(dates) => setSelectedDate(dates[0] || null)}
-      disablePast
-      shouldDisableDate={(date) =>
-        [0, 6].includes(date.getDay()) || blockedSet.has(date.toDateString())
-      }
-    />
+    <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>
   );
 }
 ```
 
-### Date Range Selector with Summary
+### Date Range Selection with Preview
 
 ```tsx
 function DateRangeSelector({ onRangeSelect }) {
-  const [range, setRange] = useState<[Date | undefined, Date | undefined]>([
-    undefined,
-    undefined,
-  ]);
+  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 dayCount = useMemo(() => {
     if (!range[0] || !range[1]) return 0;
@@ -237,76 +325,349 @@ function DateRangeSelector({ onRangeSelect }) {
       <Calendar
         rangeSelection
         value={range}
-        onChange={(dates) => {
-          setRange(dates);
-          if (dates[0] && dates[1]) onRangeSelect(dates);
-        }}
+        onChange={handleChange}
         disablePast
       />
-      {range[0] && range[1] && (
-        <Typography level="body-sm">
-          {range[0].toLocaleDateString()} - {range[1].toLocaleDateString()} ({dayCount} days)
-        </Typography>
-      )}
+      <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>
     </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
 
-1. **Prefer higher-level picker components for form fields.** Use DatePicker or DateRangePicker unless you need a custom embedded calendar UI.
+### ✅ Do
+
+1. **Use appropriate picker components for forms**: Default to DatePicker/DateRangePicker
 
 ```tsx
-// ✅ Use DatePicker for standard form input
-<DatePicker label="Birth Date" value={date} onChange={handleChange} />
+// ✅ Good: Use DatePicker for form input
+<DatePicker
+  label="Birth Date"
+  value={date}
+  onChange={(e) => setDate(e.target.value)}
+/>
+```
 
-// ❌ Using Calendar directly in a form without context
-<form>
-  <Calendar onChange={handleChange} />
-</form>
+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>
 ```
 
-2. **Handle the array value format correctly.** Calendar always uses `[start, end]` format, even for single date selection.
+3. **Use appropriate date restrictions**: Prevent invalid selections
 
 ```tsx
-// ✅ Proper single-date handling
+// ✅ 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
+/>
+```
+
+4. **Handle the array value format correctly**: Calendar always uses `[start, end]` format
+
+```tsx
+// ✅ Good: Proper value handling
+const [date, setDate] = useState<Date | null>(null);
 <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} />
+```
 
-// ❌ Treating value as a single Date
-<Calendar value={date} onChange={(d) => setDate(d)} />
+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])} />
 ```
 
-3. **Memoize `shouldDisableDate` for performance.** Complex date validation logic runs on every date cell render, so use `useCallback` or `useMemo` to prevent unnecessary recalculations.
+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:
 
 ```tsx
-// ✅ Memoized disable function
 const shouldDisableDate = useCallback((date: Date) => {
-  return [0, 6].includes(date.getDay()) || holidays.has(date.toDateString());
-}, [holidays]);
+  // 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
 
-// ❌ Inline function recreated every render
-<Calendar shouldDisableDate={(date) => expensiveCheck(date)} />
+<Calendar shouldDisableDate={shouldDisableDate} />
 ```
 
-4. **Always use Date objects, not strings.** Calendar expects native `Date` objects for `value`, `defaultValue`, `minDate`, and `maxDate`.
+### Avoid Inline Object Creation
+
+When using controlled mode, avoid creating new arrays on every render:
 
 ```tsx
-// ✅ Using Date objects
-<Calendar value={[new Date('2024-04-15'), undefined]} />
+// ❌ 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 string values
-<Calendar value={['2024-04-15', undefined]} />
+```tsx
+const handleChange = useCallback((dates: [Date | undefined, Date | undefined]) => {
+  setSelectedDate(dates[0] || null);
+}, []);
+
+<Calendar onChange={handleChange} />
 ```
 
-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.
+### Lazy Date Calculations
 
-## Accessibility
+For complex availability calculations:
+
+```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]);
+```
 
-- **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.
+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.