@transferwise/components 46.156.0 → 46.157.0

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

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

@@ -1,16 +1,23 @@
 import { useState } from 'react';
 import { StoryObj } from '@storybook/react-webpack5';
+import { fn } from 'storybook/test';
+import { action } from 'storybook/actions';
 import {
   createSandboxStory,
   globalScope,
 } from '../../../.storybook/components/sandbox/SandboxEditor';
+import { storySourceWithoutNoise } from '../../../.storybook/helpers';
 import { Size } from '../../common';
-import DateLookup, { type DateLookupProps } from '..';
 import Field from '../../Field';
+import DateLookup, { type DateLookupProps } from '..';
 
 export default {
   component: DateLookup,
   title: 'Forms/DateLookup',
+  args: {
+    onFocus: fn(),
+    onBlur: fn(),
+  },
   argTypes: {
     size: { control: 'select', options: [Size.SMALL, Size.MEDIUM, Size.LARGE] },
     disabled: { control: 'boolean' },
@@ -34,7 +41,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 +51,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 +132,115 @@ export const RightAligned: Story = {
     );
   },
 };
+
+/**
+ * Use `disabledRules` to disable specific weekdays, individual dates, or date ranges.
+ * Disabled dates remain focusable and keyboard-navigable — clicking or focusing one
+ * keeps the panel open, fires `onDateSelect` with `isEnabled: false`, and shows a
+ * negative inline prompt with the `reason` text. `min`/`max` out-of-range dates show
+ * a built-in boundary prompt (e.g. "Please select a date between 9 December 2024 and
+ * 22 January 2025.").
+ *
+ * The `reason` field is **required for accessibility**: it renders as an InlinePrompt
+ * below the grid and is linked to every disabled cell via `aria-describedby`, so screen
+ * reader users understand why a date is unavailable. For per-date reason customisation
+ * see [DisabledDatesWithDynamicReason](#disabled-dates-with-dynamic-reason).
+ */
+export const DisabledDates: Story = storySourceWithoutNoise<DateLookupProps>({
+  args: {
+    size: Size.MEDIUM,
+    label: 'Select a date',
+    placeholder: 'Choose date',
+    monthFormat: 'long',
+    min: new Date(2024, 11, 9),
+    max: new Date(2025, 0, 22),
+  },
+  render: function Render(args: DateLookupProps) {
+    const min = new Date(2024, 11, 9);
+    const max = new Date(2025, 0, 22);
+    const bankHolidays = [new Date(2024, 11, 25), new Date(2024, 11, 26), new Date(2025, 0, 1)];
+    const [value, setValue] = useState<Date | null>(null);
+
+    return (
+      <DateLookup
+        {...args}
+        min={args.min ? new Date(args.min) : undefined}
+        max={args.max ? new Date(args.max) : undefined}
+        value={value}
+        disabledRules={{
+          weekdays: ['sat', 'sun'],
+          dates: bankHolidays,
+          ranges: [{ start: new Date(2024, 11, 23), end: new Date(2024, 11, 24) }],
+          reason: 'Some dates are unavailable for this service.',
+        }}
+        onChange={(date) => {
+          action('onChange')(date);
+          setValue(date);
+        }}
+        onDateSelect={({ date, isEnabled }) => {
+          action('onDateSelect')({ date, isEnabled });
+        }}
+      />
+    );
+  },
+});
+
+/**
+ * When different disabled dates warrant different explanations, drive the `reason`
+ * dynamically from `onDateSelect`. The `isEnabled` flag tells you whether the focused
+ * date is selectable; from there you can look up the specific reason and update state.
+ *
+ * `min`/`max` out-of-range dates are handled automatically — the component shows a
+ * built-in prompt with the boundary dates, so `determineReason` only needs to cover
+ * rule-disabled dates.
+ */
+export const DisabledDatesWithDynamicReason: Story = storySourceWithoutNoise<DateLookupProps>({
+  args: {
+    size: Size.MEDIUM,
+    label: 'Select a date',
+    placeholder: 'Choose date',
+    monthFormat: 'long',
+    min: new Date(2024, 11, 9),
+    max: new Date(2025, 0, 22),
+  },
+  render: function Render(args: DateLookupProps) {
+    const DEFAULT_REASON = 'Some dates are unavailable for this service.';
+    const bankHolidays = [new Date(2024, 11, 25), new Date(2024, 11, 26), new Date(2025, 0, 1)];
+    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={args.min ? new Date(args.min) : undefined}
+        max={args.max ? new Date(args.max) : undefined}
+        value={value}
+        disabledRules={{
+          weekdays: ['sat', 'sun'],
+          dates: bankHolidays,
+          ranges: [{ start: new Date(2024, 11, 23), end: new Date(2024, 11, 24) }],
+          reason,
+        }}
+        onChange={(date) => {
+          action('onChange')(date);
+          setValue(date);
+        }}
+        onDateSelect={({ date, isEnabled }) => {
+          action('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/ExpressiveMoneyInput/CurrencySelector/CurrencySelector.tsx

@@ -1,5 +1,6 @@
 import type { AvatarLayoutProps } from '../../AvatarLayout';
 import Button from '../../Button';
+import type { NewButtonProps } from '../../Button';
 import {
   SelectInput,
   SelectInputOptionContent,
@@ -8,13 +9,7 @@ import {
 import type { CurrencyType, ExpressiveMoneyInputProps } from '../ExpressiveMoneyInput';
 import { ChevronDown } from '@transferwise/icons';
 import { Flag } from '@wise/art';
-import {
-  type ButtonHTMLAttributes,
-  forwardRef,
-  type MouseEventHandler,
-  useMemo,
-  useState,
-} from 'react';
+import { forwardRef, type MouseEventHandler, useMemo, useState } from 'react';
 import { useIntl } from 'react-intl';
 
 import messages from '../ExpressiveMoneyInput.messages';
@@ -44,6 +39,11 @@ export type CurrencySelectorProps = {
   onSearchChange?: (payload: { query: string; resultCount: number }) => void;
 } & Pick<ExpressiveMoneyInputProps, 'currency'>;
 
+type ButtonInputProps = Omit<
+  Extract<NewButtonProps, { as?: 'button' }>,
+  'v2' | 'size' | 'priority' | 'className' | 'href' | 'target'
+>;
+
 export const CurrencySelector = ({
   id,
   currency,
@@ -109,7 +109,6 @@ export const CurrencySelector = ({
       renderTrigger={() => (
         <SelectInputTriggerButton
           as={ButtonInput}
-          // @ts-expect-error new (v2) ButtonProps
           addonStart={{
             type: 'avatar',
             value: [
@@ -122,11 +121,11 @@ export const CurrencySelector = ({
                     }),
               },
             ]
-              .filter(Boolean)
+              .filter((avatar): avatar is NonNullable<typeof avatar> => avatar != null)
               .filter((avatar) => !(avatar && Object.keys(avatar).length === 0)),
           }}
           addonEnd={disabled ? undefined : { type: 'icon', value: <ChevronDown /> }}
-          onClick={(event) => handleTriggerClick(event)}
+          onClick={handleTriggerClick}
         >
           <>
             <span aria-hidden>{formatCurrencyCode(currency)}</span>
@@ -151,9 +150,9 @@ export const CurrencySelector = ({
   );
 };
 
-export const ButtonInput = forwardRef(function ButtonInput(
-  { children, ...rest }: React.PropsWithChildren<ButtonHTMLAttributes<HTMLButtonElement>>,
-  ref: React.ForwardedRef<HTMLButtonElement | null>,
+export const ButtonInput = forwardRef<HTMLButtonElement, ButtonInputProps>(function ButtonInput(
+  { children, ...rest },
+  ref,
 ) {
   return (
     <Button

package/src/Inputs/SelectInput/SelectInput.test.tsx

@@ -7,9 +7,12 @@ import { render, mockMatchMedia, mockResizeObserver } from '../../test-utils';
 import {
   SelectInput,
   SelectInputOptionContent,
+  SelectInputTriggerButton,
   type SelectInputOptionItem,
   type SelectInputProps,
 } from '.';
+import Button from '../../Button';
+import type { ButtonProps as ResolverButtonProps } from '../../Button/Button.resolver';
 import Field from '../../Field';
 
 mockMatchMedia();
@@ -337,6 +340,40 @@ describe('SelectInput', () => {
     expect(screen.getByLabelText(/Currency/)).toHaveAttribute('aria-haspopup');
   });
 
+  it('renders addonStart and addonEnd when using trigger as Button', () => {
+    type V2ButtonProps = Extract<ResolverButtonProps, { v2: true }>;
+
+    render(
+      <SelectInput
+        items={[{ type: 'option', value: 'USD' }]}
+        renderTrigger={({ content, className, size }) => {
+          const triggerButtonProps: V2ButtonProps = {
+            v2: true,
+            size,
+            className,
+            addonStart: {
+              type: 'icon',
+              value: <span data-testid="select-trigger-addon-start">Start</span>,
+            },
+            addonEnd: {
+              type: 'icon',
+              value: <span data-testid="select-trigger-addon-end">End</span>,
+            },
+          };
+
+          return (
+            <SelectInputTriggerButton as={Button} {...triggerButtonProps}>
+              {content}
+            </SelectInputTriggerButton>
+          );
+        }}
+      />,
+    );
+
+    expect(screen.getByTestId('select-trigger-addon-start')).toBeInTheDocument();
+    expect(screen.getByTestId('select-trigger-addon-end')).toBeInTheDocument();
+  });
+
   it('deduplicates search results across groups using compareValues as key', async () => {
     interface Currency {
       code: string;

package/src/Inputs/SelectInput/TriggerButton/SelectInputTriggerButton.tsx

@@ -5,7 +5,7 @@ import { PolymorphicWithOverrides } from '../../../common/PolymorphicWithOverrid
 import { Merge } from '../../../utils';
 import { SelectInputTriggerButtonPropsContext } from '../SelectInput.contexts';
 
-export type SelectInputTriggerButtonElementType = 'button' | React.ComponentType;
+export type SelectInputTriggerButtonElementType = React.ElementType;
 
 export type SelectInputTriggerButtonProps<
   T extends SelectInputTriggerButtonElementType = 'button',

package/src/Typeahead/Typeahead.css

@@ -7,6 +7,10 @@
 .typeahead .dropdown-menu {
   max-width: 100%;
   width: 100%;
+  scroll-padding-top: 8px;
+  scroll-padding-top: var(--size-8);
+  scroll-padding-bottom: 8px;
+  scroll-padding-bottom: var(--size-8);
 }
 .np-theme-personal--forest-green .typeahead .dropdown-menu,
 .np-theme-personal--bright-green .typeahead .dropdown-menu,

package/src/Typeahead/Typeahead.less

@@ -18,6 +18,8 @@
   .dropdown-menu {
     max-width: 100%;
     width: 100%;
+    scroll-padding-top: var(--size-8);
+    scroll-padding-bottom: var(--size-8);
     .np-theme-personal--forest-green &,
     .np-theme-personal--bright-green &,
     .np-theme-personal--dark & {

package/src/Typeahead/Typeahead.messages.ts

@@ -6,4 +6,9 @@ export default defineMessages({
     defaultMessage: 'Clear',
     description: 'Description of clear button',
   },
+  suggestionsLabel: {
+    id: 'neptune.Typeahead.suggestionsLabel',
+    defaultMessage: 'Suggestions',
+    description: 'Accessible label for the list of typeahead suggestions',
+  },
 });

package/src/Typeahead/Typeahead.test.tsx

@@ -1,11 +1,18 @@
 import Field from '../Field';
-import { mockMatchMedia, render, screen, fireEvent } from '../test-utils';
+import { mockMatchMedia, render, screen, fireEvent, userEvent } from '../test-utils';
 import { wait } from '../test-utils/wait';
 import Typeahead from './Typeahead';
 
 mockMatchMedia();
 
+const scrollIntoView = jest.fn();
+
 describe('Typeahead', () => {
+  beforeEach(() => {
+    HTMLElement.prototype.scrollIntoView = scrollIntoView;
+    scrollIntoView.mockClear();
+  });
+
   it('supports `Field` for labeling', () => {
     render(
       <Field id="test" label="Tags">
@@ -22,7 +29,7 @@ describe('Typeahead', () => {
           <Typeahead id="test" name="test" options={[]} onChange={() => {}} />
         </Field>,
       );
-      expect(screen.queryByRole('menu')).not.toBeInTheDocument();
+      expect(screen.queryByRole('listbox')).not.toBeInTheDocument();
     });
     it('does render a dropdown when only a footer is provided', () => {
       render(
@@ -30,7 +37,7 @@ describe('Typeahead', () => {
           <Typeahead id="test" name="test" options={[]} footer={<p>hello</p>} onChange={() => {}} />
         </Field>,
       );
-      expect(screen.getByRole('menu')).toBeInTheDocument();
+      expect(screen.getByRole('listbox')).toBeInTheDocument();
     });
   });
 
@@ -74,6 +81,76 @@ describe('Typeahead', () => {
     expect(onChange).toHaveBeenCalled();
   });
 
+  it('scrolls options into view when navigating with arrow keys', async () => {
+    render(
+      <Typeahead
+        id="test"
+        name="test"
+        options={[{ label: 'Option 1' }, { label: 'Option 2' }]}
+        minQueryLength={0}
+        onChange={() => {}}
+      />,
+    );
+    const input = screen.getByRole('combobox');
+
+    await userEvent.click(input);
+    await userEvent.keyboard('{ArrowDown}{ArrowDown}');
+
+    expect(input).toHaveFocus();
+    expect(scrollIntoView).toHaveBeenCalledTimes(2);
+    expect(scrollIntoView).toHaveBeenNthCalledWith(1, { block: 'nearest' });
+    expect(scrollIntoView).toHaveBeenNthCalledWith(2, { block: 'nearest' });
+    expect(scrollIntoView.mock.contexts[0]).toBe(screen.getByText('Option 1').closest('li'));
+    expect(scrollIntoView.mock.contexts[1]).toBe(screen.getByText('Option 2').closest('li'));
+  });
+
+  it('uses one Tab stop for the suggestions', async () => {
+    render(
+      <>
+        <Typeahead
+          id="test"
+          name="test"
+          options={[{ label: 'Option 1' }, { label: 'Option 2' }]}
+          minQueryLength={0}
+          onChange={() => {}}
+        />
+        <button type="button">Next control</button>
+      </>,
+    );
+
+    const input = screen.getByRole('combobox');
+    await userEvent.click(input);
+    await userEvent.tab();
+
+    expect(screen.getByRole('listbox')).toHaveFocus();
+    await userEvent.keyboard('{ArrowDown}');
+    expect(screen.getByRole('option', { name: 'Option 1' })).toHaveClass(
+      'tw-dropdown-item--focused',
+    );
+    expect(screen.getByRole('listbox')).toHaveFocus();
+    await userEvent.tab();
+    expect(screen.getByRole('button', { name: 'Next control' })).toHaveFocus();
+  });
+
+  it('uses the active option style when hovering a suggestion', async () => {
+    render(
+      <Typeahead
+        id="test"
+        name="test"
+        options={[{ label: 'Option 1' }, { label: 'Option 2' }]}
+        minQueryLength={0}
+        onChange={() => {}}
+      />,
+    );
+
+    await userEvent.click(screen.getByRole('combobox'));
+    await userEvent.hover(screen.getByRole('option', { name: 'Option 2' }));
+
+    expect(screen.getByRole('option', { name: 'Option 2' })).toHaveClass(
+      'tw-dropdown-item--focused',
+    );
+  });
+
   it('shows clear button when there is a value', () => {
     render(
       <Typeahead