@transferwise/components 0.0.0-experimental-c1f5b0b → 0.0.0-experimental-fe160ab

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/DateTrigger/DateTrigger.css

@@ -2,22 +2,28 @@
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
-  inline-size: 100%;
+  width: 100%;
 }
 .np-theme-personal .np-date-trigger {
-  padding-inline-start: 16px;
-  padding-inline-start: var(--size-16);
+  padding-left: 16px;
+  padding-left: var(--size-16);
 }
 .clear-btn {
   position: absolute;
-  inset-block-start: 8px;
-  inset-block-start: var(--size-8);
-  inset-inline-end: 8px;
-  inset-inline-end: var(--size-8);
+  top: 8px;
+  top: var(--size-8);
+  right: 8px;
+  right: var(--size-8);
+}
+[dir="rtl"] .clear-btn {
+  left: 8px;
+  left: var(--size-8);
+  right: auto;
+  right: initial;
 }
 .clear-btn--sm {
-  inset-block-start: 0;
+  top: 0;
 }
 .clear-btn--lg {
-  inset-block-start: 20px;
+  top: 20px;
 }

package/src/DateLookup/DateTrigger/DateTrigger.less

@@ -1,4 +1,5 @@
 @import (reference) "../../styles/variables/neptune-tokens.less";
+@import (reference) "../../styles/less/mixins/_logical-properties.less";
 
 .np-date-trigger {
   overflow: hidden;
@@ -14,7 +15,7 @@
 .clear-btn {
   position: absolute;
   top: var(--size-8);
-  right: var(--size-8);
+  .right(var(--size-8));
 
   &--sm {
     top: 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,113 @@ 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({
+  args: {
+    size: Size.MEDIUM,
+    label: 'Select a date',
+    placeholder: 'Choose date',
+    monthFormat: 'long',
+  },
+  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={min}
+        max={max}
+        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({
+  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 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);
+    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={min}
+        max={max}
+        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/Decision/Decision.less

@@ -1,3 +1,5 @@
+@import (reference) "./../styles/less/mixins/_logical-properties.less";
+
 .np-decision {
   .decision {
     display: flex;

package/src/DefinitionList/DefinitionList.css

@@ -0,0 +1,83 @@
+.tw-definition-list__item dd {
+  word-break: break-all;
+  word-break: break-word;
+}
+.tw-definition-list__action {
+  align-self: center;
+  flex-shrink: 0;
+}
+.tw-definition-list__button {
+  margin-top: -50%;
+}
+@media (max-width: 599.98px) {
+  .tw-definition-list--right-aligned-desktop {
+    justify-content: space-between;
+  }
+}
+@media (min-width: 600px) {
+  .tw-definition-list--right-aligned-desktop {
+    justify-content: flex-end;
+  }
+  .tw-definition-list.tw-definition-list--columns {
+    flex-wrap: wrap;
+  }
+  .tw-definition-list.tw-definition-list--columns .tw-definition-list__item {
+    width: 50%;
+  }
+  .tw-definition-list.tw-definition-list--horizontal .tw-definition-list__item {
+    display: flex;
+  }
+  .tw-definition-list.tw-definition-list--horizontal .tw-definition-list__item dt {
+    flex: 1;
+    min-width: 150px;
+    max-width: 30%;
+    margin-right: 8px;
+    margin-right: var(--size-8);
+  }
+  [dir="rtl"] .tw-definition-list.tw-definition-list--horizontal .tw-definition-list__item dt {
+    margin-left: 8px;
+    margin-left: var(--size-8);
+    margin-right: 0;
+    margin-right: initial;
+  }
+  .tw-definition-list.tw-definition-list--horizontal .tw-definition-list__item dd {
+    flex: 1;
+    align-items: center;
+    margin-bottom: 8px;
+    margin-bottom: var(--size-8);
+  }
+  .tw-definition-list.tw-definition-list--horizontal-right-aligned {
+    display: grid;
+    grid-template-columns: minmax(0, max-content) minmax(0, max-content);
+    grid-column-gap: 52px;
+    grid-column-gap: var(--size-52);
+    -moz-column-gap: 52px;
+         column-gap: 52px;
+    -moz-column-gap: var(--size-52);
+         column-gap: var(--size-52);
+    justify-content: space-between;
+  }
+  .tw-definition-list.tw-definition-list--horizontal-right-aligned .tw-definition-list__item {
+    display: grid;
+    grid-template-columns: subgrid;
+    grid-column: 1 / -1;
+  }
+  .tw-definition-list.tw-definition-list--horizontal-right-aligned .tw-definition-list__item dt {
+    max-width: none;
+    min-width: 0;
+    word-wrap: anywhere;
+    margin-right: 0;
+  }
+  [dir="rtl"] .tw-definition-list.tw-definition-list--horizontal-right-aligned .tw-definition-list__item dt {
+    margin-left: 0;
+    margin-right: 0;
+    margin-right: initial;
+  }
+  .tw-definition-list.tw-definition-list--horizontal-right-aligned .tw-definition-list__item dd {
+    min-width: 0;
+  }
+}
+.np-theme-personal .tw-definition-list dt {
+  color: #5d7079;
+  color: var(--color-content-secondary);
+}

package/src/DefinitionList/DefinitionList.less

@@ -1,3 +1,5 @@
+@import (reference) "./../styles/less/mixins/_logical-properties.less";
+
 .tw-definition-list {
   &__item dd {
     word-break: break-all;
@@ -40,7 +42,7 @@
           flex: 1;
           min-width: 150px;
           max-width: 30%;
-          margin-right: var(--size-8);
+          .margin(right, var(--size-8));
         }
 
         dd {