@transferwise/components 0.0.0-experimental-0df72a3 → 0.0.0-experimental-fe160ab

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

@@ -0,0 +1,293 @@
+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 with rule-disabled dates', () => {
+    it('does NOT close when a rule-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('panel behavior with out-of-range dates', () => {
+    const minDate = new Date(2024, 6, 3);
+    const maxDate = new Date(2024, 6, 25);
+
+    it('does NOT close when an out-of-range date is clicked', async () => {
+      render(
+        <DateLookup
+          value={new Date(2024, 6, 5)}
+          min={minDate}
+          max={maxDate}
+          onChange={jest.fn()}
+        />,
+      );
+
+      await openDateLookup();
+      await user.click(screen.getByRole('button', { name: /^1 July 2024/u }));
+
+      expect(screen.getByRole('dialog')).toBeInTheDocument();
+    });
+
+    it('does NOT call onChange when an out-of-range date is clicked', async () => {
+      const handleChange = jest.fn();
+      render(
+        <DateLookup
+          value={new Date(2024, 6, 5)}
+          min={minDate}
+          max={maxDate}
+          onChange={handleChange}
+        />,
+      );
+
+      await openDateLookup();
+      await user.click(screen.getByRole('button', { name: /^1 July 2024/u }));
+
+      expect(handleChange).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('prop threading', () => {
+    it('renders rule-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 out-of-range dates with aria-disabled in the calendar', async () => {
+      render(
+        <DateLookup
+          value={new Date(2024, 6, 5)}
+          min={new Date(2024, 6, 3)}
+          max={new Date(2024, 6, 25)}
+          onChange={jest.fn()}
+        />,
+      );
+
+      await openDateLookup();
+
+      const outOfRangeDate = screen.getByRole('button', { name: /^1 July 2024/u });
+      expect(outOfRangeDate).toHaveAttribute('aria-disabled', 'true');
+      expect(outOfRangeDate).toBeEnabled();
+    });
+
+    it('renders InlinePrompt with disabledRules reason text', async () => {
+      render(<DateLookup value={initialValue} disabledRules={weekendRules} onChange={jest.fn()} />);
+
+      await openDateLookup();
+
+      expect(screen.getByText('We are closed on weekends.')).toBeInTheDocument();
+    });
+
+    it('renders previous month button as disabled when min is in the current month', async () => {
+      render(
+        <DateLookup value={new Date(2024, 6, 5)} min={new Date(2024, 6, 1)} onChange={jest.fn()} />,
+      );
+
+      await openDateLookup();
+
+      expect(screen.getByRole('button', { name: /previous month/iu })).toBeDisabled();
+    });
+
+    it('renders next month button as disabled when max is in the current month', async () => {
+      render(
+        <DateLookup
+          value={new Date(2024, 6, 5)}
+          max={new Date(2024, 6, 31)}
+          onChange={jest.fn()}
+        />,
+      );
+
+      await openDateLookup();
+
+      expect(screen.getByRole('button', { name: /next month/iu })).toBeDisabled();
+    });
+  });
+
+  describe('InlinePrompt for out-of-range dates', () => {
+    const minDate = new Date(2024, 6, 3);
+    const maxDate = new Date(2024, 6, 25);
+
+    it('shows negative prompt with boundary dates when out-of-range date is clicked', async () => {
+      render(
+        <DateLookup
+          value={new Date(2024, 6, 5)}
+          min={minDate}
+          max={maxDate}
+          onChange={jest.fn()}
+        />,
+      );
+
+      await openDateLookup();
+      await user.click(screen.getByRole('button', { name: /^1 July 2024/u }));
+
+      // The prompt renders inside a portal so query from document
+      const prompt = document.querySelector('.wds-inline-prompt');
+      expect(prompt).toBeInTheDocument();
+      expect(prompt).toHaveClass('wds-prompt--negative');
+      expect(prompt).toHaveTextContent(
+        'Please select a date between 3 July 2024 and 25 July 2024.',
+      );
+    });
+
+    it('shows boundary message (not disabledRules reason) when out-of-range date is clicked', async () => {
+      render(
+        <DateLookup
+          value={new Date(2024, 6, 5)}
+          min={minDate}
+          max={maxDate}
+          disabledRules={weekendRules}
+          onChange={jest.fn()}
+        />,
+      );
+
+      await openDateLookup();
+      // July 27 is beyond max
+      await user.click(screen.getByRole('button', { name: /^27 July 2024/u }));
+
+      const prompt = document.querySelector('.wds-inline-prompt');
+      expect(prompt).toHaveTextContent(
+        'Please select a date between 3 July 2024 and 25 July 2024.',
+      );
+      expect(prompt).not.toHaveTextContent('We are closed on weekends.');
+    });
+  });
+
+  describe('onDateSelect', () => {
+    it('fires with isEnabled: false when navigating to a rule-disabled date', 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,
+        }),
+      );
+    });
+
+    it('fires with isEnabled: false when clicking an out-of-range date', async () => {
+      const handleDateSelect = jest.fn();
+      render(
+        <DateLookup
+          value={new Date(2024, 6, 5)}
+          min={new Date(2024, 6, 3)}
+          max={new Date(2024, 6, 25)}
+          onChange={jest.fn()}
+          onDateSelect={handleDateSelect}
+        />,
+      );
+
+      await openDateLookup();
+      await user.click(screen.getByRole('button', { name: /^1 July 2024/u }));
+
+      expect(handleDateSelect).toHaveBeenCalledWith(
+        expect.objectContaining({
+          date: new Date(2024, 6, 1),
+          isEnabled: false,
+        }),
+      );
+    });
+
+    it('fires with isEnabled: true when clicking an enabled date', async () => {
+      const handleDateSelect = jest.fn();
+      render(
+        <DateLookup
+          value={new Date(2024, 6, 5)}
+          disabledRules={weekendRules}
+          onChange={jest.fn()}
+          onDateSelect={handleDateSelect}
+        />,
+      );
+
+      await openDateLookup();
+      await user.click(screen.getByLabelText(/^3 July 2024/u));
+
+      expect(handleDateSelect).toHaveBeenCalledWith(
+        expect.objectContaining({
+          date: new Date(2024, 6, 3),
+          isEnabled: true,
+        }),
+      );
+    });
+  });
+});

package/src/DateLookup/DateLookup.test.tsx

@@ -110,24 +110,13 @@ describe('DateLookup', () => {
       ['{ArrowRight}', +1],
       ['{ArrowUp}', -7],
       ['{ArrowDown}', +7],
-    ])("handles '%s' to step %d day(s)", async (text: string, step: number) => {
+    ])("handles '%s' to step %d day(s) without changing value", async (text: string) => {
       const handleChange = jest.fn();
       await setupAndOpenWithMouse({ onChange: handleChange });
 
-      expect(handleChange).not.toHaveBeenCalled();
-
       await user.keyboard(text);
 
-      const value = new Date(initialValue);
-      value.setDate(initialValue.getDate() + step);
-      expect(handleChange).toHaveBeenCalledWith(value);
-
-      await user.keyboard('{Escape}');
-      await act(async () => {
-        await jest.runOnlyPendingTimersAsync();
-      });
-
-      expect(handleChange).toHaveBeenCalledWith(initialValue);
+      expect(handleChange).not.toHaveBeenCalled();
     });
   });
 
@@ -137,7 +126,7 @@ describe('DateLookup', () => {
       ['{ArrowRight}', +1],
       ['{ArrowUp}', -4],
       ['{ArrowDown}', +4],
-    ])("handles '%s' to step %d year(s)", async (text: string, step: number) => {
+    ])("handles '%s' to step %d year(s) without changing value", async (text: string) => {
       const handleChange = jest.fn();
       await setupAndOpenWithMouse({ onChange: handleChange });
 
@@ -146,20 +135,9 @@ describe('DateLookup', () => {
         await jest.runOnlyPendingTimersAsync();
       });
 
-      expect(handleChange).not.toHaveBeenCalled();
-
       await user.keyboard(text);
 
-      const value = new Date(initialValue);
-      value.setFullYear(initialValue.getFullYear() + step);
-      expect(handleChange).toHaveBeenCalledWith(value);
-
-      await user.keyboard('{Escape}');
-      await act(async () => {
-        await jest.runOnlyPendingTimersAsync();
-      });
-
-      expect(handleChange).toHaveBeenCalledWith(initialValue);
+      expect(handleChange).not.toHaveBeenCalled();
     });
   });
 
@@ -169,7 +147,7 @@ describe('DateLookup', () => {
       ['{ArrowRight}', +1],
       ['{ArrowUp}', -4],
       ['{ArrowDown}', +4],
-    ])("handles '%s' to step %d month(s)", async (text: string, step: number) => {
+    ])("handles '%s' to step %d month(s) without changing value", async (text: string) => {
       const handleChange = jest.fn();
       await setupAndOpenWithMouse({ onChange: handleChange });
 
@@ -182,20 +160,39 @@ describe('DateLookup', () => {
         await jest.runOnlyPendingTimersAsync();
       });
 
+      await user.keyboard(text);
+
       expect(handleChange).not.toHaveBeenCalled();
+    });
+  });
 
-      await user.keyboard(text);
+  describe('focus vs selection separation', () => {
+    it('does not call onChange during arrow key navigation', async () => {
+      const handleChange = jest.fn();
+      render(<DateLookup value={new Date(2020, 0, 15)} onChange={handleChange} />);
 
-      const value = new Date(initialValue);
-      value.setMonth(initialValue.getMonth() + step);
-      expect(handleChange).toHaveBeenCalledWith(value);
+      // Open the panel
+      await user.click(screen.getByRole('button'));
+      expect(handleChange).not.toHaveBeenCalled();
 
-      await user.keyboard('{Escape}');
-      await act(async () => {
-        await jest.runOnlyPendingTimersAsync();
-      });
+      await user.keyboard('{ArrowRight}');
 
-      expect(handleChange).toHaveBeenCalledWith(initialValue);
+      expect(handleChange).not.toHaveBeenCalled();
+    });
+
+    it('calls onChange when Enter is pressed on a focused date', async () => {
+      const handleChange = jest.fn();
+      render(<DateLookup value={new Date(2020, 0, 15)} onChange={handleChange} />);
+
+      // Open the panel
+      await user.click(screen.getByRole('button'));
+      expect(handleChange).not.toHaveBeenCalled();
+
+      // Arrow to next date then confirm with Enter
+      await user.keyboard('{ArrowRight}');
+      await user.keyboard('{Enter}');
+
+      expect(handleChange).toHaveBeenCalledWith(new Date(2020, 0, 16));
     });
   });
 });
@@ -229,7 +226,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,
@@ -15,19 +16,37 @@ import { OverlayIdProvider } from '../Provider/overlay/OverlayIdProvider';
 import DateTrigger from './DateTrigger';
 
 export interface DateLookupProps {
-  id?: string;
+  /** The currently selected date, or `null` for no selection. */
   value: Date | null;
+  /** Called when an enabled date is confirmed. Receives `null` when the value is cleared. */
+  onChange: (date: Date | null) => void;
+  /** HTML `id` applied to the trigger button, used for label association. */
+  id?: string;
+  /** 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;
+  /** Size of the trigger input. Defaults to `'md'`. */
   size?: SizeSmall | SizeMedium | SizeLarge;
-  placeholder?: string;
+  /** Label text rendered above the trigger input. */
   label?: string;
+  /** ID of an external element that labels the trigger, for use inside custom label contexts. */
   'aria-labelledby'?: string;
+  /** Placeholder text shown in the trigger when no date is selected. */
+  placeholder?: string;
+  /** Month name format in the calendar header. Defaults to `'long'` (e.g. "January"). */
   monthFormat?: `${MonthFormat}`;
+  /** When `true`, the trigger and calendar are non-interactive. */
   disabled?: boolean;
+  /** When `true`, a clear button is shown in the trigger to reset the value to `null`. */
   clearable?: boolean;
-  onChange: (date: Date | null) => 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 any date is focused or clicked, including disabled and out-of-range dates. `isEnabled` is `false` when the date is not selectable. */
+  onDateSelect?: (params: OnDateSelectParams) => void;
+  /** Called when the calendar panel opens. */
   onFocus?: () => void;
+  /** Called when the calendar panel closes. */
   onBlur?: () => void;
 }
 
@@ -128,7 +147,15 @@ class DateLookup extends PureComponent<DateLookupPropsWithInputAttributes, DateL
     }
   };
 
-  handleDateChange = (date: Date | null) => {
+  handleDateChange = (date: Date | null, meta: DateChangeMeta) => {
+    const { onDateSelect } = this.props;
+    if (date && onDateSelect) {
+      onDateSelect({ date, isEnabled: meta.isEnabled });
+    }
+  };
+
+  handleDateSelect = (date: Date | null) => {
+    if (!date) return;
     this.setState(
       (state) => {
         const originalDate = state.originalDate ?? this.props.value;
@@ -136,18 +163,14 @@ class DateLookup extends PureComponent<DateLookupPropsWithInputAttributes, DateL
       },
       () => {
         this.props.onChange(date);
+        this.close();
+        this.focusOn('.btn');
       },
     );
   };
 
-  handleDateSelect = (date: Date) => {
-    this.props.onChange(date);
-    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,8 +179,9 @@ class DateLookup extends PureComponent<DateLookupPropsWithInputAttributes, DateL
           max={max}
           monthFormat={monthFormat}
           placeholder={placeholder}
-          onChange={this.handleDateChange}
-          onSelect={this.handleDateSelect}
+          disabledRules={disabledRules}
+          onDateFocus={this.handleDateChange}
+          onChange={this.handleDateSelect}
         />
       </div>
     );

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

@@ -0,0 +1,108 @@
+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 (via `disabledRules`)
+
+When `disabledRules` is provided, disabled dates remain focusable and keyboard-navigable:
+
+- `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
+
+## Out-of-Range Dates (via `min`/`max`)
+
+Dates outside `min`/`max` boundaries use `aria-disabled="true"` (not the native HTML `disabled` attribute). They are rendered as interactive buttons in the grid and can be clicked; the `aria-label` appends "not available". Arrow key navigation clamps at the boundary, so keyboard users cannot navigate into out-of-range cells.
+
+This distinction is intentional: `min`/`max` defines a hard boundary, while `disabledRules` marks dates that exist but are unavailable (users can discover them and understand why via the InlinePrompt).
+
+### 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