@transferwise/components 46.156.0 → 46.157.0

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

@@ -0,0 +1,114 @@
+import type { Meta, StoryObj } from '@storybook/react-webpack5';
+import { expect, waitFor, within, userEvent } from 'storybook/test';
+
+import Calendar from '../Calendar';
+import type { DisabledRules } from '../Calendar.types';
+
+export default {
+  component: Calendar,
+  title: 'Forms/Calendar/Tests',
+  tags: ['!autodocs', '!manifest'],
+} satisfies Meta<typeof Calendar>;
+
+type Story = StoryObj<typeof Calendar>;
+
+// min: March 2024, max: October 2024
+const min = new Date(2024, 2, 1);
+const max = new Date(2024, 9, 31);
+
+/**
+ * Year view: years within min/max are enabled, years outside are disabled (aria-disabled),
+ * and both navigation arrows are disabled because min and max fall within the same 2020–2039 block.
+ */
+export const YearViewBoundaries: Story = {
+  render: () => <Calendar value={new Date(2024, 5, 15)} min={min} max={max} />,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    await userEvent.click(canvas.getByRole('button', { name: /year view/iu }));
+
+    // Selected year (within range) is enabled
+    await expect(
+      canvas.getByRole('button', { name: /2024.*selected year/iu }),
+    ).not.toHaveAttribute('aria-disabled');
+
+    // Adjacent years outside range are disabled
+    await expect(
+      canvas.getByRole('button', { name: /^2023.*not available/iu }),
+    ).toHaveAttribute('aria-disabled', 'true');
+    await expect(
+      canvas.getByRole('button', { name: /^2025.*not available/iu }),
+    ).toHaveAttribute('aria-disabled', 'true');
+
+    // Both nav arrows disabled — min and max are both in the 2020–2039 block
+    await expect(canvas.getByRole('button', { name: /previous 20 years/iu })).toBeDisabled();
+    await expect(canvas.getByRole('button', { name: /next 20 years/iu })).toBeDisabled();
+  },
+};
+
+/**
+ * Month view: months within min/max are enabled, months outside are disabled (aria-disabled),
+ * and both navigation arrows are disabled because min and max are both in 2024.
+ */
+export const MonthViewBoundaries: Story = {
+  render: () => <Calendar value={new Date(2024, 5, 15)} min={min} max={max} />,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    // Navigate: year view → click 2024 → month view
+    await userEvent.click(canvas.getByRole('button', { name: /year view/iu }));
+    await userEvent.click(canvas.getByRole('button', { name: /2024.*selected year/iu }));
+
+    // Selected month (within range) is enabled
+    await expect(
+      canvas.getByRole('button', { name: /^Jun.*selected month/iu }),
+    ).not.toHaveAttribute('aria-disabled');
+
+    // Boundary months (min=Mar, max=Oct) are enabled
+    await expect(
+      canvas.getByRole('button', { name: /^Mar(?!.*not available)/iu }),
+    ).not.toHaveAttribute('aria-disabled');
+    await expect(
+      canvas.getByRole('button', { name: /^Oct(?!.*not available)/iu }),
+    ).not.toHaveAttribute('aria-disabled');
+
+    // Months outside range are disabled
+    await expect(
+      canvas.getByRole('button', { name: /^Feb.*not available/iu }),
+    ).toHaveAttribute('aria-disabled', 'true');
+    await expect(
+      canvas.getByRole('button', { name: /^Nov.*not available/iu }),
+    ).toHaveAttribute('aria-disabled', 'true');
+
+    // Both nav arrows disabled — min and max are both in 2024
+    await expect(canvas.getByRole('button', { name: /previous year/iu })).toBeDisabled();
+    await expect(canvas.getByRole('button', { name: /next year/iu })).toBeDisabled();
+  },
+};
+
+const disabledRules: DisabledRules = {
+  weekdays: ['sat', 'sun'],
+  reason: 'We are closed on weekends.',
+};
+
+/**
+ * When a disabled cell receives direct DOM focus (e.g. screen reader virtual cursor),
+ * the inline prompt updates to negative sentiment showing the disabled reason.
+ */
+export const DisabledDateFocusUpdatesPrompt: Story = {
+  render: () => <Calendar value={new Date(2024, 6, 5)} disabledRules={disabledRules} />,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    // Initially prompt is neutral (focused date is enabled)
+    const prompt = canvasElement.querySelector('.wds-inline-prompt')!;
+    await expect(prompt).toHaveClass('wds-prompt--neutral');
+
+    // Simulate screen reader focus on a disabled Saturday (matches both "6 July 2024" and "July 6, 2024")
+    const saturday = canvas.getByLabelText(/(?:6 July|July 6).*2024/u);
+    saturday.focus();
+
+    // Prompt should switch to negative after React re-render
+    await waitFor(() => expect(prompt).toHaveClass('wds-prompt--negative'));
+  },
+};

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,312 @@
+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,
+        }),
+      );
+    });
+
+    it('fires exactly once when an enabled date is clicked', async () => {
+      const handleDateSelect = jest.fn();
+      render(
+        <DateLookup
+          value={new Date(2024, 6, 5)}
+          disabledRules={weekendRules}
+          onChange={jest.fn()}
+          onDateSelect={handleDateSelect}
+        />,
+      );
+
+      await openDateLookup();
+      handleDateSelect.mockClear();
+
+      await user.click(screen.getByLabelText(/^3 July 2024/u));
+
+      expect(handleDateSelect).toHaveBeenCalledTimes(1);
+    });
+  });
+});

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>
     );