@transferwise/components 0.0.0-experimental-bcea1dd → 0.0.0-experimental-1168b1c

package/src/Calendar/_stories/Calendar.accessibility.docs.mdx

@@ -0,0 +1,112 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Forms/Calendar/Accessibility" />
+
+# Accessibility
+
+Calendar is a fully keyboard-accessible date picker grid. All dates — including disabled ones — are reachable via keyboard so that screen reader users can discover which dates are unavailable and why.
+
+## Keyboard Support
+
+<table>
+  <thead>
+    <tr>
+      <th>Key</th>
+      <th>Action</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>
+        <code>ArrowLeft</code>
+      </td>
+      <td>Move focus to previous day / month / year</td>
+    </tr>
+    <tr>
+      <td>
+        <code>ArrowRight</code>
+      </td>
+      <td>Move focus to next day / month / year</td>
+    </tr>
+    <tr>
+      <td>
+        <code>ArrowUp</code>
+      </td>
+      <td>Move focus up by one week (7 days) / 4 months / 4 years</td>
+    </tr>
+    <tr>
+      <td>
+        <code>ArrowDown</code>
+      </td>
+      <td>Move focus down by one week (7 days) / 4 months / 4 years</td>
+    </tr>
+    <tr>
+      <td>
+        <code>Enter</code> / <code>Space</code>
+      </td>
+      <td>Select the focused date (if enabled)</td>
+    </tr>
+  </tbody>
+</table>
+
+<br /> Navigation **does not skip** disabled dates. Users can arrow through every date in the grid
+regardless of its enabled state.
+
+## Screen Reader Announcements
+
+Each date cell is a `<button>` with an `aria-label` in a human-readable long format (e.g. "6 July 2024") constructed via `Intl.DateTimeFormat` for full locale support.
+
+### Active (Selected) Date
+
+The currently selected date includes "selected day" in its aria-label:
+
+> "6 July 2024, selected day"
+
+### Disabled Dates
+
+Disabled date cells are announced with additional context:
+
+- `aria-disabled="true"` signals the date is not selectable
+- The aria-label appends "not available" (e.g. "6 July 2024, not available")
+- `aria-describedby` links to the InlinePrompt element containing the reason text
+
+This means a screen reader will announce something like:
+
+> "6 July 2024, not available — We are closed on weekends. button, dimmed."
+
+### Disabled + Selected
+
+If the focused date is both active and disabled:
+
+> "6 July 2024, selected day, not available"
+
+## InlinePrompt Behaviour
+
+An `InlinePrompt` renders below the day grid when the current month contains disabled dates. It displays the `disabledRules.reason` text.
+
+### When It Appears
+
+The prompt is visible when **all** of the following are true:
+
+1. The Calendar is in day view
+2. `disabledRules.reason` is provided
+3. The currently displayed month contains at least one disabled date
+
+### How It's Announced
+
+The prompt is linked to disabled date cells via `aria-describedby`. This means the reason text is read as a description when a disabled cell receives focus — screen readers announce it after the label and role.
+
+The prompt element has an `id` that matches the `aria-describedby` on each disabled cell. It is **not** a live region (`role="alert"` or `role="status"`) because:
+
+- It does not change dynamically while focus is on a disabled cell
+- Announcing it on every arrow key press would be disruptive
+- The `aria-describedby` relationship already ensures it's read on focus
+
+### Sentiment
+
+The prompt's visual sentiment changes based on the currently focused date:
+
+- **Negative** (red) — when the focused date is disabled
+- **Neutral** — when the focused date is enabled
+
+This is a visual-only change and does not affect screen reader output.

package/src/Calendar/_stories/Calendar.story.tsx

@@ -5,6 +5,7 @@ import {
   createSandboxStory,
   globalScope,
 } from '../../../.storybook/components/sandbox/SandboxEditor';
+import { storySourceWithoutNoise } from '../../../.storybook/helpers';
 import Calendar, { type CalendarProps } from '../Calendar';
 import Modal from '../../Modal';
 import Button from '../../Button';
@@ -30,12 +31,17 @@ thePast.setUTCDate(epoch.getUTCDate() - 10);
 
 export const Sandbox = createSandboxStory({
   code: `const App = () => {
-  const [value, setValue] = React.useState(new Date('2024-06-15'));
+  const [value, setValue] = React.useState(new Date(2024, 5, 18));
 
   return (
     <Calendar
       monthFormat="long"
       value={value}
+      disabledRules={{
+        weekdays: ['sat', 'sun'],
+        dates: [new Date(2024, 5, 19)],
+        reason: 'Weekends and holidays are unavailable.',
+      }}
       onChange={(date) => setValue(date)}
     />
   );
@@ -102,3 +108,51 @@ export const InsideModal: Story = {
     await userEvent.click(canvas.getByRole('button', { name: 'Open modal' }));
   },
 };
+
+/**
+ * Use `disabledRules` to disable specific weekdays, individual dates, or even date ranges.
+ * For accessibility purposes, the `reason` field is required and renders as an InlinePrompt
+ * below the calendar grid.
+ *
+ * If you want to customise the `reason` on per-date basis, use the `isEnabled` meta
+ * from `onChange` to determine and update the reason dynamically.
+ */
+export const DisabledDates: Story = storySourceWithoutNoise({
+  render: function Render() {
+    const DEFAULT_REASON = 'Some dates are unavailable for this service.';
+    const bankHolidays = [new Date(2025, 6, 4), new Date(2025, 6, 14)];
+    const [value, setValue] = useState<Date | null>(new Date(2025, 6, 15));
+    const [reason, setReason] = useState(DEFAULT_REASON);
+
+    function determineReason(date: Date, isEnabled: boolean): string {
+      if (isEnabled) return DEFAULT_REASON;
+      if (bankHolidays.some((holiday) => holiday.toDateString() === date.toDateString())) {
+        return 'This date is a bank holiday.';
+      }
+      if (date.getDay() === 0 || date.getDay() === 6) {
+        return 'We do not operate on weekends.';
+      }
+      return 'This date is unavailable due to scheduled maintenance.';
+    }
+
+    return (
+      <Calendar
+        value={value}
+        min={new Date(2025, 6, 1)}
+        max={new Date(2025, 7, 31)}
+        disabledRules={{
+          weekdays: ['sat', 'sun'],
+          dates: bankHolidays,
+          ranges: [{ start: new Date(2025, 7, 11), end: new Date(2025, 7, 15) }],
+          reason,
+        }}
+        onChange={(date, { isEnabled }) => {
+          setValue(date);
+          if (date) {
+            setReason(determineReason(date, isEnabled));
+          }
+        }}
+      />
+    );
+  },
+});

package/src/Calendar/index.ts

@@ -1,2 +1,9 @@
 export { default } from './Calendar';
 export type { CalendarProps } from './Calendar';
+export type {
+  DateChangeMeta,
+  DisabledRules,
+  DisabledDateRange,
+  WeekDayType,
+  OnDateSelectParams,
+} from './Calendar.types';

package/src/DateLookup/DateLookup.disabledDates.test.tsx

@@ -0,0 +1,120 @@
+import { mockMatchMedia, mockResizeObserver, render, screen, userEvent } from '../test-utils';
+import DateLookup from './DateLookup';
+import type { DisabledRules } from '../Calendar/Calendar.types';
+
+import { act } from 'react';
+
+const user = userEvent.setup({ advanceTimers: jest.advanceTimersByTimeAsync });
+
+mockMatchMedia();
+mockResizeObserver();
+
+const initialValue = new Date(2024, 6, 1);
+
+const weekendRules: DisabledRules = {
+  weekdays: ['sat', 'sun'],
+  reason: 'We are closed on weekends.',
+};
+
+const bankHolidayRules: DisabledRules = {
+  dates: [new Date(2024, 6, 4)],
+  reason: 'Bank holiday.',
+};
+
+describe('DateLookup - disabled dates', () => {
+  beforeEach(() => {
+    jest.useFakeTimers();
+  });
+
+  afterEach(async () => {
+    await jest.runOnlyPendingTimersAsync();
+    jest.useRealTimers();
+    jest.clearAllMocks();
+  });
+
+  const openDateLookup = async () => {
+    await user.click(screen.getByRole('button'));
+    await act(async () => {
+      await jest.runOnlyPendingTimersAsync();
+    });
+  };
+
+  describe('panel behavior', () => {
+    it('does NOT close when a disabled date is clicked', async () => {
+      render(
+        <DateLookup value={initialValue} disabledRules={bankHolidayRules} onChange={jest.fn()} />,
+      );
+
+      await openDateLookup();
+      const holiday = screen.getByLabelText(/^4 July 2024/u);
+      await user.click(holiday);
+
+      expect(screen.getByRole('dialog')).toBeInTheDocument();
+    });
+
+    it('closes when an enabled date is clicked', async () => {
+      const handleChange = jest.fn();
+      render(
+        <DateLookup
+          value={initialValue}
+          disabledRules={bankHolidayRules}
+          onChange={handleChange}
+        />,
+      );
+
+      await openDateLookup();
+      const enabledDate = screen.getByLabelText(/^3 July 2024/u);
+      await user.click(enabledDate);
+
+      await act(async () => {
+        await jest.runOnlyPendingTimersAsync();
+      });
+
+      expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
+      expect(handleChange).toHaveBeenCalledWith(new Date(2024, 6, 3));
+    });
+  });
+
+  describe('prop threading', () => {
+    it('renders disabled dates with aria-disabled in the calendar', async () => {
+      render(<DateLookup value={initialValue} disabledRules={weekendRules} onChange={jest.fn()} />);
+
+      await openDateLookup();
+
+      const saturday = screen.getByLabelText(/^6 July 2024/u);
+      expect(saturday).toHaveAttribute('aria-disabled', 'true');
+    });
+
+    it('renders InlinePrompt with reason text', async () => {
+      render(<DateLookup value={initialValue} disabledRules={weekendRules} onChange={jest.fn()} />);
+
+      await openDateLookup();
+
+      expect(screen.getByText('We are closed on weekends.')).toBeInTheDocument();
+    });
+  });
+
+  describe('onDateSelect', () => {
+    it('fires when navigating with arrow keys', async () => {
+      const handleDateSelect = jest.fn();
+      render(
+        <DateLookup
+          value={new Date(2024, 6, 5)}
+          disabledRules={weekendRules}
+          onChange={jest.fn()}
+          onDateSelect={handleDateSelect}
+        />,
+      );
+
+      await openDateLookup();
+      await user.keyboard('{ArrowRight}');
+
+      expect(handleDateSelect).toHaveBeenCalledWith(
+        expect.objectContaining({
+          date: new Date(2024, 6, 6),
+          isEnabled: false,
+        }),
+      );
+    });
+  });
+});

package/src/DateLookup/DateLookup.test.tsx

@@ -229,7 +229,7 @@ describe('DateLookup (events)', () => {
     const today = new Date();
     const todayDateLabel = today.toLocaleDateString('en-GB', {
       day: 'numeric',
-      month: 'numeric',
+      month: 'long',
       year: 'numeric',
     });
     const expectedHeaderText = today.toLocaleDateString('en-GB', {

package/src/DateLookup/DateLookup.tsx

@@ -1,6 +1,7 @@
 import { clsx } from 'clsx';
 import { createRef, PureComponent, KeyboardEvent } from 'react';
 import Calendar from '../Calendar';
+import type { DateChangeMeta, DisabledRules, OnDateSelectParams } from '../Calendar/Calendar.types';
 import {
   Size,
   MonthFormat,
@@ -26,7 +27,9 @@ export interface DateLookupProps {
   monthFormat?: `${MonthFormat}`;
   disabled?: boolean;
   clearable?: boolean;
+  disabledRules?: DisabledRules;
   onChange: (date: Date | null) => void;
+  onDateSelect?: (params: OnDateSelectParams) => void;
   onFocus?: () => void;
   onBlur?: () => void;
 }
@@ -128,7 +131,8 @@ class DateLookup extends PureComponent<DateLookupPropsWithInputAttributes, DateL
     }
   };
 
-  handleDateChange = (date: Date | null) => {
+  handleDateChange = (date: Date | null, meta: DateChangeMeta) => {
+    const { onDateSelect } = this.props;
     this.setState(
       (state) => {
         const originalDate = state.originalDate ?? this.props.value;
@@ -136,18 +140,20 @@ class DateLookup extends PureComponent<DateLookupPropsWithInputAttributes, DateL
       },
       () => {
         this.props.onChange(date);
+        if (date && onDateSelect) {
+          onDateSelect({ date, isEnabled: meta.isEnabled });
+        }
       },
     );
   };
 
-  handleDateSelect = (date: Date) => {
-    this.props.onChange(date);
+  handleDateSelect = () => {
     this.close();
     this.focusOn('.btn');
   };
 
   getCalendar = () => {
-    const { value, min, max, monthFormat, placeholder } = this.props;
+    const { value, min, max, monthFormat, placeholder, disabledRules } = this.props;
     return (
       <div className="p-a-1">
         <Calendar
@@ -156,6 +162,7 @@ class DateLookup extends PureComponent<DateLookupPropsWithInputAttributes, DateL
           max={max}
           monthFormat={monthFormat}
           placeholder={placeholder}
+          disabledRules={disabledRules}
           onChange={this.handleDateChange}
           onSelect={this.handleDateSelect}
         />

package/src/DateLookup/_stories/DateLookup.accessibility.docs.mdx

@@ -0,0 +1,100 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Forms/DateLookup/Accessibility" />
+
+# Accessibility
+
+DateLookup wraps the Calendar component inside a dropdown panel. It provides full keyboard accessibility for opening, navigating, selecting, and dismissing dates.
+
+## Keyboard Support
+
+<table>
+  <thead>
+    <tr>
+      <th>Key</th>
+      <th>Context</th>
+      <th>Action</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>
+        <code>ArrowLeft/Right/Up/Down</code>
+      </td>
+      <td>Trigger focused, panel closed</td>
+      <td>Opens the panel</td>
+    </tr>
+    <tr>
+      <td>
+        <code>ArrowLeft/Right/Up/Down</code>
+      </td>
+      <td>Panel open</td>
+      <td>Navigates between dates (see Calendar)</td>
+    </tr>
+    <tr>
+      <td>
+        <code>Enter</code> / <code>Space</code>
+      </td>
+      <td>Panel open, enabled date focused</td>
+      <td>Selects date, closes panel</td>
+    </tr>
+    <tr>
+      <td><code>Enter</code> / <code>Space</code></td>
+      <td>Panel open, disabled date focused</td>
+      <td>No action (panel stays open)</td>
+    </tr>
+    <tr>
+      <td>
+        <code>Escape</code>
+      </td>
+      <td>Panel open</td>
+      <td>Reverts to original value, closes panel</td>
+    </tr>
+  </tbody>
+</table>
+
+<br />
+
+### Click Behaviour
+
+- **Clicking an enabled date**: selects it, closes the panel, fires `onChange`
+- **Clicking a disabled date**: does not select, panel stays open, focus remains in the calendar grid
+
+## Screen Reader Announcements
+
+DateLookup relies on the Calendar's built-in accessibility features for date announcements. See [Calendar
+Accessibility](?path=/docs/forms-calendar-accessibility--docs) for details on how dates are labelled and described.
+
+### Trigger Button
+
+The trigger button announces the currently selected date (or placeholder text when no date is selected). It uses `aria-controls` to associate with the panel.
+
+### Panel
+
+The dropdown panel is rendered with `role="dialog"` and is connected to the trigger via `aria-controls`. When opened, focus moves into the calendar grid.
+
+## Disabled Dates
+
+When `disabledRules` is provided, disabled dates behave identically to the Calendar component:
+
+- `aria-disabled="true"` marks the cell as unavailable
+- "not available" is appended to the aria-label
+- `aria-describedby` links to the InlinePrompt reason text
+- Keyboard navigation reaches disabled dates (they are not skipped)
+- Clicking or pressing Enter on a disabled date does **not** close the panel
+
+### InlinePrompt
+
+An InlinePrompt renders below the day grid inside the panel when the visible month contains disabled dates. It displays the configured `disabledRules.reason` text.
+
+The prompt is linked to disabled cells via `aria-describedby`, so screen readers announce the reason when a disabled
+date receives focus. See [Calendar Accessibility](?path=/docs/forms-calendar-accessibility--docs) for full details on
+the prompt's announcement behaviour.
+
+## Consumer Callbacks
+
+The `onDateSelect` callback fires with `{ date, isEnabled }` whenever the user navigates to or clicks on any date. Consumers can use this to:
+
+- Display a custom message explaining why a specific date is disabled
+- Track which dates users attempt to select
+- Provide alternative actions for disabled dates

package/src/DateLookup/_stories/DateLookup.story.tsx

@@ -7,6 +7,7 @@ import {
 import { Size } from '../../common';
 import DateLookup, { type DateLookupProps } from '..';
 import Field from '../../Field';
+import { storySourceWithoutNoise } from '../../../.storybook/helpers';
 
 export default {
   component: DateLookup,
@@ -34,7 +35,7 @@ thePast.setUTCDate(epoch.getUTCDate() - 10);
 
 export const Sandbox = createSandboxStory({
   code: `const App = () => {
-  const [value, setValue] = React.useState(new Date('2024-06-15'));
+  const [value, setValue] = React.useState(new Date(2024, 5, 14));
 
   return (
     <DateLookup
@@ -44,6 +45,11 @@ export const Sandbox = createSandboxStory({
       placeholder="Choose date"
       clearable
       value={value}
+      disabledRules={{
+        weekdays: ['sat', 'sun'],
+        dates: [new Date(2024, 5, 19)],
+        reason: 'Weekends and holidays are unavailable.',
+      }}
       onChange={(date) => setValue(date)}
     />
   );
@@ -120,3 +126,55 @@ export const RightAligned: Story = {
     );
   },
 };
+
+/**
+ * Use `disabledRules` to disable specific weekdays, individual dates, or even date ranges.
+ * For accessibility purposes, the `reason` field is required and renders as an InlinePrompt
+ * below the calendar grid.
+ *
+ * If you want to customise the `reason` on per-date basis, you can use `onDateSelect`.
+ */
+export const DisabledDates: Story = storySourceWithoutNoise({
+  args: {
+    size: Size.MEDIUM,
+    label: 'Select a date',
+    placeholder: 'Choose date',
+    monthFormat: 'long',
+  },
+  render: function Render(args: DateLookupProps) {
+    const DEFAULT_REASON = 'Some dates are unavailable for this service.';
+    const bankHolidays = [new Date(2025, 6, 14), new Date(2025, 7, 25)];
+    const [value, setValue] = useState<Date | null>(null);
+    const [reason, setReason] = useState(DEFAULT_REASON);
+
+    function determineReason(date: Date, isEnabled: boolean): string {
+      if (isEnabled) return DEFAULT_REASON;
+      if (bankHolidays.some((holiday) => holiday.toDateString() === date.toDateString())) {
+        return 'This date is a bank holiday.';
+      }
+      if (date.getDay() === 0 || date.getDay() === 6) {
+        return 'We do not operate on weekends.';
+      }
+      return 'This date is unavailable due to scheduled maintenance.';
+    }
+
+    return (
+      <DateLookup
+        {...args}
+        min={new Date(2025, 6, 1)}
+        max={new Date(2025, 7, 31)}
+        value={value}
+        disabledRules={{
+          weekdays: ['sat', 'sun'],
+          dates: bankHolidays,
+          ranges: [{ start: new Date(2025, 6, 21), end: new Date(2025, 6, 25) }],
+          reason,
+        }}
+        onChange={(date) => setValue(date)}
+        onDateSelect={({ date, isEnabled }) => {
+          setReason(determineReason(date, isEnabled));
+        }}
+      />
+    );
+  },
+});

package/src/DateLookup/index.ts

@@ -1,2 +1,8 @@
 export { default } from './DateLookup';
 export type { DateLookupProps } from './DateLookup';
+export type {
+  DisabledRules,
+  DisabledDateRange,
+  WeekDayType,
+  OnDateSelectParams,
+} from '../Calendar/Calendar.types';

package/src/common/DateUtils/hasDisabledDatesInMonth/hasDisabledDatesInMonth.test.ts

@@ -0,0 +1,98 @@
+import { hasDisabledDatesInMonth } from './hasDisabledDatesInMonth';
+import type { DisabledRules } from '../../../Calendar/Calendar.types';
+
+describe('hasDisabledDatesInMonth', () => {
+  describe('weekdays', () => {
+    it('returns true when weekday rules exist (every month has all weekdays)', () => {
+      const rules: DisabledRules = { weekdays: ['sat', 'sun'], reason: 'Closed' };
+      expect(hasDisabledDatesInMonth(6, 2024, rules)).toBe(true);
+    });
+
+    it('returns true for any month when weekday rules exist', () => {
+      const rules: DisabledRules = { weekdays: ['mon'], reason: 'Closed' };
+      expect(hasDisabledDatesInMonth(0, 2024, rules)).toBe(true);
+      expect(hasDisabledDatesInMonth(11, 2024, rules)).toBe(true);
+    });
+
+    it('returns false when weekdays array is empty', () => {
+      const rules: DisabledRules = { weekdays: [], reason: 'None' };
+      expect(hasDisabledDatesInMonth(6, 2024, rules)).toBe(false);
+    });
+  });
+
+  describe('specific dates', () => {
+    const rules: DisabledRules = {
+      dates: [new Date(2024, 6, 11), new Date(2024, 6, 25), new Date(2025, 0, 1)],
+      reason: 'Bank holidays',
+    };
+
+    it('returns true when month contains a disabled date', () => {
+      expect(hasDisabledDatesInMonth(6, 2024, rules)).toBe(true);
+    });
+
+    it('returns false when month has no disabled dates', () => {
+      expect(hasDisabledDatesInMonth(5, 2024, rules)).toBe(false);
+    });
+
+    it('returns true for another year with disabled date', () => {
+      expect(hasDisabledDatesInMonth(0, 2025, rules)).toBe(true);
+    });
+  });
+
+  describe('ranges', () => {
+    const rules: DisabledRules = {
+      ranges: [{ start: new Date(2024, 2, 29), end: new Date(2024, 3, 3) }],
+      reason: 'Maintenance',
+    };
+
+    it('returns true when range starts in the month', () => {
+      expect(hasDisabledDatesInMonth(2, 2024, rules)).toBe(true);
+    });
+
+    it('returns true when range ends in the month', () => {
+      expect(hasDisabledDatesInMonth(3, 2024, rules)).toBe(true);
+    });
+
+    it('returns true when range spans the entire month', () => {
+      const spanRules: DisabledRules = {
+        ranges: [{ start: new Date(2024, 0, 1), end: new Date(2024, 11, 31) }],
+        reason: 'Year-long',
+      };
+      expect(hasDisabledDatesInMonth(6, 2024, spanRules)).toBe(true);
+    });
+
+    it('returns false when range does not overlap the month', () => {
+      expect(hasDisabledDatesInMonth(4, 2024, rules)).toBe(false);
+    });
+  });
+
+  describe('min/max constraints', () => {
+    it('returns false when all disabled dates in month are outside min/max', () => {
+      const rules: DisabledRules = {
+        dates: [new Date(2024, 6, 1), new Date(2024, 6, 2)],
+        reason: 'Early',
+      };
+      const min = new Date(2024, 6, 10);
+      const max = new Date(2024, 6, 31);
+      expect(hasDisabledDatesInMonth(6, 2024, rules, min, max)).toBe(false);
+    });
+
+    it('returns true when weekdays exist regardless of min/max', () => {
+      const rules: DisabledRules = { weekdays: ['sat'], reason: 'Closed' };
+      const min = new Date(2024, 6, 10);
+      const max = new Date(2024, 6, 20);
+      expect(hasDisabledDatesInMonth(6, 2024, rules, min, max)).toBe(true);
+    });
+  });
+
+  describe('no rules', () => {
+    it('returns false when disabledRules is undefined', () => {
+      expect(hasDisabledDatesInMonth(6, 2024, undefined)).toBe(false);
+    });
+
+    it('returns false when only reason is provided', () => {
+      const rules: DisabledRules = { reason: 'Reason only' };
+      expect(hasDisabledDatesInMonth(6, 2024, rules)).toBe(false);
+    });
+  });
+});