@transferwise/components 0.0.0-experimental-15273df → 0.0.0-experimental-d6d5b6e

package/src/Calendar/Calendar.test.tsx

@@ -1,5 +1,6 @@
 import { mockMatchMedia, render, screen, userEvent } from '../test-utils';
 import Calendar from './Calendar';
+import type { DisabledRules } from './Calendar.types';
 
 mockMatchMedia();
 
@@ -15,35 +16,87 @@ describe('Calendar', () => {
       ['{ArrowUp}', -7],
       ['{ArrowDown}', +7],
     ])("handles '%s' to step %d day(s)", async (text: string, step: number) => {
-      const handleChange = jest.fn();
-      render(<Calendar value={initialValue} onChange={handleChange} />);
+      const handleDateFocus = jest.fn();
+      render(<Calendar value={initialValue} onDateFocus={handleDateFocus} />);
 
       await user.click(screen.getByRole('button', { name: /selected day/iu }));
       await user.keyboard(text);
 
       const expected = new Date(initialValue);
       expected.setDate(initialValue.getDate() + step);
-      expect(handleChange).toHaveBeenCalledWith(expected);
+      expect(handleDateFocus).toHaveBeenCalledWith(expected, { isEnabled: true });
     });
 
     it('selects a day on click', async () => {
+      const handleDateFocus = jest.fn();
+      render(<Calendar value={initialValue} onDateFocus={handleDateFocus} />);
+
+      await user.click(screen.getByText('15'));
+
+      expect(handleDateFocus).toHaveBeenCalledWith(new Date(2000, 0, 15), { isEnabled: true });
+    });
+
+    it('fires both onDateFocus and onChange when clicking a day', async () => {
+      const handleDateFocus = jest.fn();
       const handleChange = jest.fn();
-      render(<Calendar value={initialValue} onChange={handleChange} />);
+      render(
+        <Calendar value={initialValue} onDateFocus={handleDateFocus} onChange={handleChange} />,
+      );
 
       await user.click(screen.getByText('15'));
 
+      expect(handleDateFocus).toHaveBeenCalledWith(new Date(2000, 0, 15), { isEnabled: true });
       expect(handleChange).toHaveBeenCalledWith(new Date(2000, 0, 15));
     });
 
-    it('calls onSelect instead of onChange when clicking a day', async () => {
+    it('does not fire onChange during arrow key navigation', async () => {
       const handleChange = jest.fn();
-      const handleSelect = jest.fn();
-      render(<Calendar value={initialValue} onChange={handleChange} onSelect={handleSelect} />);
+      render(<Calendar value={initialValue} onChange={handleChange} />);
 
-      await user.click(screen.getByText('15'));
+      await user.click(screen.getByRole('button', { name: /selected day/iu }));
+      expect(handleChange).toHaveBeenCalledTimes(1);
 
-      expect(handleSelect).toHaveBeenCalledWith(new Date(2000, 0, 15));
-      expect(handleChange).not.toHaveBeenCalled();
+      await user.keyboard('{ArrowRight}');
+
+      expect(handleChange).toHaveBeenCalledTimes(1);
+    });
+
+    it('fires onChange when Enter is pressed on focused date', async () => {
+      const handleChange = jest.fn();
+      render(<Calendar value={initialValue} onChange={handleChange} />);
+
+      await user.click(screen.getByRole('button', { name: /selected day/iu }));
+      await user.keyboard('{ArrowRight}');
+      await user.keyboard('{Enter}');
+
+      const expected = new Date(initialValue);
+      expected.setDate(initialValue.getDate() + 1);
+      expect(handleChange).toHaveBeenCalledWith(expected);
+    });
+
+    it('does not fire onChange when Enter is pressed on a disabled focused date', async () => {
+      const handleChange = jest.fn();
+      const disabledRules: DisabledRules = {
+        weekdays: ['sat', 'sun'],
+        reason: 'Closed on weekends.',
+      };
+      render(
+        <Calendar
+          value={new Date(2000, 0, 7)}
+          disabledRules={disabledRules}
+          onChange={handleChange}
+        />,
+      );
+
+      await user.click(screen.getByRole('button', { name: /selected day/iu }));
+      // Click on selected day (Friday) fires onChange once
+      expect(handleChange).toHaveBeenCalledTimes(1);
+
+      // ArrowRight from Jan 7 (Friday) → Jan 8 (Saturday = disabled)
+      await user.keyboard('{ArrowRight}');
+      await user.keyboard('{Enter}');
+
+      expect(handleChange).toHaveBeenCalledTimes(1);
     });
   });
 
@@ -54,15 +107,15 @@ describe('Calendar', () => {
       ['{ArrowUp}', -4],
       ['{ArrowDown}', +4],
     ])("handles '%s' to step %d year(s)", async (text: string, step: number) => {
-      const handleChange = jest.fn();
-      render(<Calendar value={initialValue} onChange={handleChange} />);
+      const handleDateFocus = jest.fn();
+      render(<Calendar value={initialValue} onDateFocus={handleDateFocus} />);
 
       await user.click(screen.getByRole('button', { name: /year view/iu }));
       await user.keyboard(text);
 
       const expected = new Date(initialValue);
       expected.setFullYear(initialValue.getFullYear() + step);
-      expect(handleChange).toHaveBeenCalledWith(expected);
+      expect(handleDateFocus).toHaveBeenCalledWith(expected, { isEnabled: true });
     });
   });
 
@@ -73,8 +126,8 @@ describe('Calendar', () => {
       ['{ArrowUp}', -4],
       ['{ArrowDown}', +4],
     ])("handles '%s' to step %d month(s)", async (text: string, step: number) => {
-      const handleChange = jest.fn();
-      render(<Calendar value={initialValue} onChange={handleChange} />);
+      const handleDateFocus = jest.fn();
+      render(<Calendar value={initialValue} onDateFocus={handleDateFocus} />);
 
       await user.click(screen.getByRole('button', { name: /year view/iu }));
       await user.keyboard(' ');
@@ -82,48 +135,166 @@ describe('Calendar', () => {
 
       const expected = new Date(initialValue);
       expected.setMonth(initialValue.getMonth() + step);
-      expect(handleChange).toHaveBeenCalledWith(expected);
+      expect(handleDateFocus).toHaveBeenCalledWith(expected, { isEnabled: true });
     });
   });
 
   describe('min/max clamping', () => {
-    it('limits navigation to min value', async () => {
+    it('limits keyboard navigation to min value', async () => {
       const min = new Date(initialValue);
       min.setDate(min.getDate() - 1);
-      const handleChange = jest.fn();
-      render(<Calendar value={initialValue} min={min} onChange={handleChange} />);
+      const handleDateFocus = jest.fn();
+      render(<Calendar value={initialValue} min={min} onDateFocus={handleDateFocus} />);
 
       await user.click(screen.getByRole('button', { name: /selected day/iu }));
       await user.keyboard('{ArrowLeft}{ArrowLeft}');
 
-      expect(handleChange).toHaveBeenLastCalledWith(min);
+      expect(handleDateFocus).toHaveBeenLastCalledWith(min, { isEnabled: true });
     });
 
-    it('limits navigation to max value', async () => {
+    it('limits keyboard navigation to max value', async () => {
       const max = new Date(initialValue);
       max.setDate(max.getDate() + 1);
-      const handleChange = jest.fn();
-      render(<Calendar value={initialValue} max={max} onChange={handleChange} />);
+      const handleDateFocus = jest.fn();
+      render(<Calendar value={initialValue} max={max} onDateFocus={handleDateFocus} />);
 
       await user.click(screen.getByRole('button', { name: /selected day/iu }));
       await user.keyboard('{ArrowRight}{ArrowRight}');
 
-      expect(handleChange).toHaveBeenLastCalledWith(max);
+      expect(handleDateFocus).toHaveBeenLastCalledWith(max, { isEnabled: true });
     });
 
     it('clamps value to range when value is outside min/max', () => {
       const min = new Date(2000, 0, 5);
       const max = new Date(2000, 0, 20);
-      const handleChange = jest.fn();
-      render(<Calendar value={initialValue} min={min} max={max} onChange={handleChange} />);
+      const handleDateFocus = jest.fn();
+      render(<Calendar value={initialValue} min={min} max={max} onDateFocus={handleDateFocus} />);
 
-      expect(handleChange).toHaveBeenCalledWith(min);
+      expect(handleDateFocus).toHaveBeenCalledWith(min, { isEnabled: true });
+    });
+  });
+
+  describe('navigation button boundary disabling', () => {
+    describe('day view — previous/next month', () => {
+      it('disables previous month button when min is in the current view month', () => {
+        render(<Calendar value={new Date(2000, 3, 15)} min={new Date(2000, 3, 1)} />);
+        expect(screen.getByRole('button', { name: /previous month/iu })).toBeDisabled();
+      });
+
+      it('disables next month button when max is in the current view month', () => {
+        render(<Calendar value={new Date(2000, 3, 15)} max={new Date(2000, 3, 30)} />);
+        expect(screen.getByRole('button', { name: /next month/iu })).toBeDisabled();
+      });
+
+      it('does not disable month buttons when min/max are in adjacent months', () => {
+        render(
+          <Calendar
+            value={new Date(2000, 3, 15)}
+            min={new Date(2000, 2, 1)}
+            max={new Date(2000, 4, 30)}
+          />,
+        );
+        expect(screen.getByRole('button', { name: /previous month/iu })).toBeEnabled();
+        expect(screen.getByRole('button', { name: /next month/iu })).toBeEnabled();
+      });
+
+      it('does not disable month buttons when no min/max is set', () => {
+        render(<Calendar value={new Date(2000, 3, 15)} />);
+        expect(screen.getByRole('button', { name: /previous month/iu })).toBeEnabled();
+        expect(screen.getByRole('button', { name: /next month/iu })).toBeEnabled();
+      });
+
+      it('disables previous month button when min is in January and view is January', () => {
+        // Edge case: month wraps to previous year
+        render(<Calendar value={new Date(2000, 0, 15)} min={new Date(2000, 0, 1)} />);
+        expect(screen.getByRole('button', { name: /previous month/iu })).toBeDisabled();
+      });
+
+      it('disables next month button when max is in December and view is December', () => {
+        // Edge case: month wraps to next year
+        render(<Calendar value={new Date(2000, 11, 15)} max={new Date(2000, 11, 31)} />);
+        expect(screen.getByRole('button', { name: /next month/iu })).toBeDisabled();
+      });
+    });
+
+    describe('month view — previous/next year', () => {
+      it('disables previous year button when min year equals view year', async () => {
+        render(<Calendar value={new Date(2000, 3, 15)} min={new Date(2000, 0, 1)} />);
+        await user.click(screen.getByRole('button', { name: /year view/iu }));
+        await user.click(screen.getByRole('button', { name: /2000, selected year/iu }));
+        expect(screen.getByRole('button', { name: /previous year/iu })).toBeDisabled();
+      });
+
+      it('disables next year button when max year equals view year', async () => {
+        render(<Calendar value={new Date(2000, 3, 15)} max={new Date(2000, 11, 31)} />);
+        await user.click(screen.getByRole('button', { name: /year view/iu }));
+        await user.click(screen.getByRole('button', { name: /2000, selected year/iu }));
+        expect(screen.getByRole('button', { name: /next year/iu })).toBeDisabled();
+      });
+
+      it('does not disable year buttons when min/max are in adjacent years', async () => {
+        render(
+          <Calendar
+            value={new Date(2000, 3, 15)}
+            min={new Date(1999, 0, 1)}
+            max={new Date(2001, 11, 31)}
+          />,
+        );
+        await user.click(screen.getByRole('button', { name: /year view/iu }));
+        await user.click(screen.getByRole('button', { name: /2000, selected year/iu }));
+        expect(screen.getByRole('button', { name: /previous year/iu })).toBeEnabled();
+        expect(screen.getByRole('button', { name: /next year/iu })).toBeEnabled();
+      });
+
+      it('does not disable year buttons when no min/max is set', async () => {
+        render(<Calendar value={new Date(2000, 3, 15)} />);
+        await user.click(screen.getByRole('button', { name: /year view/iu }));
+        await user.click(screen.getByRole('button', { name: /2000, selected year/iu }));
+        expect(screen.getByRole('button', { name: /previous year/iu })).toBeEnabled();
+        expect(screen.getByRole('button', { name: /next year/iu })).toBeEnabled();
+      });
+    });
+
+    describe('year view — previous/next 20 years', () => {
+      it('disables previous 20-year button when min falls in the current block', async () => {
+        // value is 2000, block is 2000–2019, min is 2005 → previous block (1980–1999) is entirely before min
+        render(<Calendar value={new Date(2005, 0, 1)} min={new Date(2005, 0, 1)} />);
+        await user.click(screen.getByRole('button', { name: /year view/iu }));
+        expect(screen.getByRole('button', { name: /previous 20 years/iu })).toBeDisabled();
+      });
+
+      it('disables next 20-year button when max falls in the current block', async () => {
+        // value is 2000, block is 2000–2019, max is 2015 → next block (2020–2039) is entirely after max
+        render(<Calendar value={new Date(2000, 0, 1)} max={new Date(2015, 11, 31)} />);
+        await user.click(screen.getByRole('button', { name: /year view/iu }));
+        expect(screen.getByRole('button', { name: /next 20 years/iu })).toBeDisabled();
+      });
+
+      it('does not disable 20-year buttons when min/max span multiple blocks', async () => {
+        render(
+          <Calendar
+            value={new Date(2000, 0, 1)}
+            min={new Date(1985, 0, 1)}
+            max={new Date(2025, 11, 31)}
+          />,
+        );
+        await user.click(screen.getByRole('button', { name: /year view/iu }));
+        expect(screen.getByRole('button', { name: /previous 20 years/iu })).toBeEnabled();
+        expect(screen.getByRole('button', { name: /next 20 years/iu })).toBeEnabled();
+      });
+
+      it('does not disable 20-year buttons when no min/max is set', async () => {
+        render(<Calendar value={new Date(2000, 0, 1)} />);
+        await user.click(screen.getByRole('button', { name: /year view/iu }));
+        expect(screen.getByRole('button', { name: /previous 20 years/iu })).toBeEnabled();
+        expect(screen.getByRole('button', { name: /next 20 years/iu })).toBeEnabled();
+      });
     });
   });
 
   describe('view switching', () => {
     it('switches to year view and back to day view', async () => {
-      render(<Calendar value={initialValue} onChange={jest.fn()} />);
+      render(<Calendar value={initialValue} />);
 
       await user.click(screen.getByRole('button', { name: /year view/iu }));
       expect(screen.getByRole('button', { name: /selected year/iu })).toBeInTheDocument();
@@ -134,5 +305,23 @@ describe('Calendar', () => {
       await user.click(screen.getByRole('button', { name: /selected month/iu }));
       expect(screen.getByRole('button', { name: /next month/iu })).toBeInTheDocument();
     });
+
+    it('switches to year view when header button is activated with keyboard', async () => {
+      const handleChange = jest.fn();
+      render(<Calendar value={initialValue} onChange={handleChange} />);
+
+      // Tab through to the year view header button
+      const yearViewButton = screen.getByRole('button', { name: /year view/iu });
+      await user.tab();
+      while (document.activeElement !== yearViewButton) {
+        await user.tab();
+      }
+      expect(yearViewButton).toHaveFocus();
+
+      await user.keyboard('{Enter}');
+
+      expect(screen.getByRole('button', { name: /selected year/iu })).toBeInTheDocument();
+      expect(handleChange).not.toHaveBeenCalled();
+    });
   });
 });

package/src/Calendar/Calendar.tsx

@@ -1,40 +1,88 @@
-import { useState, useCallback, useEffect, KeyboardEvent } from 'react';
+import { useState, useCallback, useEffect, useId, useRef, KeyboardEvent } from 'react';
+import { useIntl } from 'react-intl';
+import { formatDate } from '@transferwise/formatting';
 
 import { MonthFormat } from '../common';
-import { isWithinRange, moveToWithinRange, returnDateView } from '../common/DateUtils';
+import {
+  isWithinRange,
+  moveToWithinRange,
+  returnDateView,
+  isDateDisabled,
+  hasDisabledDatesInMonth,
+} from '../common/DateUtils';
+import { InlinePrompt } from '../Prompt/InlinePrompt';
+import type { DateChangeMeta, DisabledRules } from './Calendar.types';
 import DayCalendar from './DayCalendar';
 import { getStartOfDay } from './GetStartOfDay';
+import messages from './Calendar.messages';
 import MonthCalendar from './MonthCalendar';
 import YearCalendar from './YearCalendar';
 
 export interface CalendarProps {
+  /** The currently selected date, or `null` for no selection. */
   value: Date | null;
+  /** Earliest selectable date (inclusive). Dates before this are interactive but not selectable, and show a boundary prompt. */
   min?: Date | null;
+  /** Latest selectable date (inclusive). Dates after this are interactive but not selectable, and show a boundary prompt. */
   max?: Date | null;
+  /** Month name format in the header. Defaults to `'long'` (e.g. "January"). */
   monthFormat?: `${MonthFormat}`;
+  /** Placeholder text shown in the month/year cells when no date is selected. */
   placeholder?: string;
-  onChange: (date: Date | null) => void;
-  onSelect?: (date: Date) => void;
+  /** Rules for disabling specific weekdays, individual dates, or date ranges. The required `reason` is shown in an inline prompt and linked to disabled cells via `aria-describedby` for screen reader accessibility. */
+  disabledRules?: DisabledRules;
+  /** Called whenever the focused date changes — including disabled and out-of-range dates. `meta.isEnabled` is `false` when the date is not selectable. */
+  onDateFocus?: (date: Date | null, meta: DateChangeMeta) => void;
+  /** Called when a date is confirmed (click or Enter). Only fires for enabled dates. */
+  onChange?: (date: Date) => void;
 }
 
+/**
+ * Inline calendar for selecting a single date. Powers [DateLookup](?path=/docs/forms-datelookup--docs).
+ */
 const Calendar = ({
   value,
   min: minProp = null,
   max: maxProp = null,
   monthFormat = MonthFormat.LONG,
   placeholder,
+  disabledRules,
+  onDateFocus,
   onChange,
-  onSelect,
 }: CalendarProps) => {
+  const intl = useIntl();
   const selectedDate = getStartOfDay(value);
   const min = getStartOfDay(minProp);
   const max = getStartOfDay(maxProp);
+  const disabledReasonId = useId();
+  const disabledRulesRef = useRef(disabledRules);
+  useEffect(() => {
+    disabledRulesRef.current = disabledRules;
+  });
+
+  const [focusedDate, setFocusedDate] = useState<Date | null>(selectedDate);
+
+  useEffect(() => {
+    // eslint-disable-next-line react-hooks/set-state-in-effect
+    setFocusedDate(selectedDate);
+  }, [selectedDate?.getTime()]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const checkIsEnabled = (date: Date | null) => {
+    if (!date) return true;
+    return isWithinRange(date, min, max) && !isDateDisabled(date, disabledRulesRef.current);
+  };
+
+  const focusedDateDisabled = focusedDate
+    ? !isWithinRange(focusedDate, min, max) || isDateDisabled(focusedDate, disabledRules)
+    : false;
 
   useEffect(() => {
     if (selectedDate && !isWithinRange(selectedDate, min, max)) {
-      onChange(moveToWithinRange(selectedDate, min, max));
+      const clamped = moveToWithinRange(selectedDate, min, max);
+      setFocusedDate(clamped); // eslint-disable-line react-hooks/set-state-in-effect
+      onDateFocus?.(clamped, { isEnabled: checkIsEnabled(clamped) });
     }
-  }, [selectedDate?.getTime(), min?.getTime(), max?.getTime(), onChange]); // eslint-disable-line react-hooks/exhaustive-deps
+  }, [selectedDate?.getTime(), min?.getTime(), max?.getTime(), onDateFocus]); // eslint-disable-line react-hooks/exhaustive-deps
 
   const dateView = returnDateView(selectedDate, min, max);
   const [viewMonth, setViewMonth] = useState(dateView.getMonth());
@@ -49,6 +97,14 @@ const Calendar = ({
     setViewYear(view.getFullYear());
   }, [selectedDate?.getTime(), min?.getTime(), max?.getTime()]); // eslint-disable-line react-hooks/exhaustive-deps
 
+  useEffect(() => {
+    if (focusedDate) {
+      // eslint-disable-next-line react-hooks/set-state-in-effect
+      setViewMonth(focusedDate.getMonth());
+      setViewYear(focusedDate.getFullYear());
+    }
+  }, [focusedDate?.getTime()]); // eslint-disable-line react-hooks/exhaustive-deps
+
   const handleViewDateUpdate = useCallback(
     // eslint-disable-next-line react-hooks/preserve-manual-memoization
     ({ month, year }: { month?: number; year?: number }) => {
@@ -64,33 +120,36 @@ const Calendar = ({
 
   const handleSelectedDateUpdate = useCallback(
     (date: Date) => {
-      if (onSelect) {
-        onSelect(date);
-      } else {
+      const isEnabled = checkIsEnabled(date);
+      setFocusedDate(date);
+      onDateFocus?.(date, { isEnabled });
+      if (isEnabled && onChange) {
         onChange(date);
       }
     },
-    [onChange, onSelect],
+    [onDateFocus, onChange], // eslint-disable-line react-hooks/exhaustive-deps
   );
 
   const adjustDate = useCallback(
     (daysToAdd: number, monthsToAdd: number, yearsToAdd: number) => {
+      const base = focusedDate ?? selectedDate;
       let date: Date | null;
-      if (selectedDate) {
+      if (base) {
         date = new Date(
-          mode === 'year' ? selectedDate.getFullYear() + yearsToAdd : selectedDate.getFullYear(),
-          mode === 'month' ? selectedDate.getMonth() + monthsToAdd : selectedDate.getMonth(),
-          mode === 'day' ? selectedDate.getDate() + daysToAdd : selectedDate.getDate(),
+          mode === 'year' ? base.getFullYear() + yearsToAdd : base.getFullYear(),
+          mode === 'month' ? base.getMonth() + monthsToAdd : base.getMonth(),
+          mode === 'day' ? base.getDate() + daysToAdd : base.getDate(),
         );
       } else {
         date = getStartOfDay(new Date());
       }
       date &&= moveToWithinRange(date, min, max);
-      if (date?.getTime() !== selectedDate?.getTime()) {
-        onChange(date);
+      if (date?.getTime() !== focusedDate?.getTime()) {
+        setFocusedDate(date);
+        onDateFocus?.(date, { isEnabled: checkIsEnabled(date) });
       }
     },
-    [selectedDate, min, max, mode, onChange],
+    [focusedDate, selectedDate, min, max, mode, onDateFocus], // eslint-disable-line react-hooks/exhaustive-deps
   );
 
   const handleKeyDown = useCallback(
@@ -112,24 +171,70 @@ const Calendar = ({
           adjustDate(7, 4, 4);
           event.preventDefault();
           break;
+        case 'Enter':
+        case ' ':
+          if (
+            mode === 'day' &&
+            focusedDate &&
+            (event.target as HTMLElement).hasAttribute('data-calendar-cell')
+          ) {
+            handleSelectedDateUpdate(focusedDate);
+            event.preventDefault();
+          }
+          break;
         default:
           break;
       }
     },
-    [adjustDate],
+    [adjustDate, focusedDate, mode, handleSelectedDateUpdate],  
   );
 
+  const focusedDateOutOfRange = focusedDate ? !isWithinRange(focusedDate, min, max) : false;
+
+  const formatDateForPrompt = (date: Date) =>
+    formatDate(date, intl.locale, { day: 'numeric', month: 'long', year: 'numeric' });
+
+  const outOfRangePromptText =
+    min && max
+      ? intl.formatMessage(messages.outOfRangeBetween, {
+          min: formatDateForPrompt(min),
+          max: formatDateForPrompt(max),
+        })
+      : min
+        ? intl.formatMessage(messages.outOfRangeAfter, { min: formatDateForPrompt(min) })
+        : max
+          ? intl.formatMessage(messages.outOfRangeBefore, { max: formatDateForPrompt(max) })
+          : '';
+
+  const hasOutOfRangeDates = mode === 'day' && !!(min || max);
+  const showRulesPrompt =
+    mode === 'day' &&
+    !!disabledRules &&
+    hasDisabledDatesInMonth(viewMonth, viewYear, disabledRules, min, max);
+  const showOutOfRangePrompt = mode === 'day' && focusedDateOutOfRange;
+  const showPrompt = hasOutOfRangeDates || showRulesPrompt;
+
+  const promptText = showOutOfRangePrompt
+    ? outOfRangePromptText
+    : (disabledRules?.reason ?? outOfRangePromptText);
+  const promptSentiment = showOutOfRangePrompt || focusedDateDisabled ? 'negative' : 'neutral';
+  const promptClassName =
+    showOutOfRangePrompt || (showRulesPrompt && !showOutOfRangePrompt) ? 'm-t-1' : 'sr-only';
+
   return (
     // eslint-disable-next-line jsx-a11y/no-static-element-interactions
     <div onKeyDown={handleKeyDown}>
       {mode === 'day' && (
         <DayCalendar
           selectedDate={selectedDate}
+          focusedDate={focusedDate}
           min={min}
           max={max}
           viewMonth={viewMonth}
           viewYear={viewYear}
           monthFormat={monthFormat}
+          disabledRules={disabledRules}
+          disabledReasonId={showPrompt ? disabledReasonId : undefined}
           onSelect={handleSelectedDateUpdate}
           onLabelClick={switchToYears}
           onViewDateUpdate={handleViewDateUpdate}
@@ -138,6 +243,7 @@ const Calendar = ({
       {mode === 'month' && (
         <MonthCalendar
           selectedDate={selectedDate}
+          focusedDate={focusedDate}
           min={min}
           max={max}
           viewYear={viewYear}
@@ -150,6 +256,7 @@ const Calendar = ({
       {mode === 'year' && (
         <YearCalendar
           selectedDate={selectedDate}
+          focusedDate={focusedDate}
           min={min}
           max={max}
           viewYear={viewYear}
@@ -158,6 +265,16 @@ const Calendar = ({
           onViewDateUpdate={handleViewDateUpdate}
         />
       )}
+      {showPrompt && (
+        <InlinePrompt
+          sentiment={promptSentiment}
+          width="full"
+          id={disabledReasonId}
+          className={promptClassName}
+        >
+          {promptText}
+        </InlinePrompt>
+      )}
     </div>
   );
 };

package/src/Calendar/Calendar.types.ts

@@ -0,0 +1,35 @@
+export interface DisabledDateRange {
+  start: Date;
+  end: Date;
+}
+
+export type WeekDayType = 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat' | 'sun';
+
+export interface DisabledRules {
+  /** Days of the week to disable (e.g. `['sat', 'sun']` for weekends). */
+  weekdays?: WeekDayType[];
+  /** Specific calendar dates to disable. */
+  dates?: Date[];
+  /** Inclusive date ranges to disable. */
+  ranges?: DisabledDateRange[];
+  /**
+   * Human-readable explanation shown in an InlinePrompt below the calendar grid when a
+   * disabled date is focused or clicked. Required for accessibility: it is linked to
+   * disabled cells via `aria-describedby` so screen reader users understand why a date
+   * is unavailable. Also used as the prompt text when `min`/`max` out-of-range dates
+   * are focused, overriding the built-in default message.
+   */
+  reason: string;
+}
+
+export interface DateChangeMeta {
+  /** Whether the focused date is selectable (not disabled or out of range). */
+  isEnabled: boolean;
+}
+
+export interface OnDateSelectParams {
+  /** The date that was focused or clicked. */
+  date: Date;
+  /** Whether the date is selectable (not disabled or out of range). */
+  isEnabled: boolean;
+}

package/src/Calendar/DateHeader/DateHeader.tsx

@@ -15,6 +15,8 @@ interface DateHeaderProps {
   onPreviousClick: () => void;
   onNextClick: () => void;
   dateMode: string;
+  isPreviousDisabled?: boolean;
+  isNextDisabled?: boolean;
 }
 
 const DateHeader: React.FC<DateHeaderProps> = ({
@@ -23,6 +25,8 @@ const DateHeader: React.FC<DateHeaderProps> = ({
   onPreviousClick,
   onNextClick,
   dateMode,
+  isPreviousDisabled,
+  isNextDisabled,
 }) => {
   const intl = useIntl();
   const { isMobile } = useLayout();
@@ -34,6 +38,7 @@ const DateHeader: React.FC<DateHeaderProps> = ({
           priority="minimal"
           className="d-inline-flex"
           aria-label={`${intl.formatMessage(messages.previous)} ${dateMode}`}
+          disabled={isPreviousDisabled}
           onClick={onPreviousClick}
         >
           <ChevronLeft className="left-single-direction" />
@@ -61,6 +66,7 @@ const DateHeader: React.FC<DateHeaderProps> = ({
           className="d-inline-flex"
           aria-label={`${intl.formatMessage(messages.next)} ${dateMode}`}
           priority="minimal"
+          disabled={isNextDisabled}
           onClick={onNextClick}
         >
           <ChevronRight className="right-single-direction" />