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

package/src/Calendar/_helpers/isDateDisabled/isDateDisabled.test.ts

@@ -0,0 +1,169 @@
+import { isDateDisabled } from './isDateDisabled';
+import type { DisabledRules } from '../../Calendar.types';
+
+describe('isDateDisabled', () => {
+  describe('when no rules provided', () => {
+    it('returns false when disabledRules is undefined', () => {
+      expect(isDateDisabled(new Date('2024-07-15'), undefined)).toBe(false);
+    });
+
+    it('returns false when disabledRules has only reason', () => {
+      const rules: DisabledRules = { reason: 'some reason' };
+      expect(isDateDisabled(new Date('2024-07-15'), rules)).toBe(false);
+    });
+  });
+
+  describe('weekdays', () => {
+    const rules: DisabledRules = {
+      weekdays: ['sat', 'sun'],
+      reason: 'Closed on weekends',
+    };
+
+    it('returns true for a Saturday', () => {
+      // 2024-07-13 is a Saturday
+      expect(isDateDisabled(new Date(2024, 6, 13), rules)).toBe(true);
+    });
+
+    it('returns true for a Sunday', () => {
+      // 2024-07-14 is a Sunday
+      expect(isDateDisabled(new Date(2024, 6, 14), rules)).toBe(true);
+    });
+
+    it('returns false for a Monday', () => {
+      // 2024-07-15 is a Monday
+      expect(isDateDisabled(new Date(2024, 6, 15), rules)).toBe(false);
+    });
+
+    it('returns false for a Friday', () => {
+      // 2024-07-12 is a Friday
+      expect(isDateDisabled(new Date(2024, 6, 12), rules)).toBe(false);
+    });
+
+    it('handles single weekday rule', () => {
+      const singleDay: DisabledRules = { weekdays: ['wed'], reason: 'Closed' };
+      // 2024-07-17 is a Wednesday
+      expect(isDateDisabled(new Date(2024, 6, 17), singleDay)).toBe(true);
+      // 2024-07-18 is a Thursday
+      expect(isDateDisabled(new Date(2024, 6, 18), singleDay)).toBe(false);
+    });
+  });
+
+  describe('specific dates', () => {
+    const rules: DisabledRules = {
+      dates: [new Date(2024, 6, 11), new Date(2025, 1, 12), new Date(2025, 4, 1)],
+      reason: 'Bank holidays',
+    };
+
+    it('returns true for a disabled date', () => {
+      expect(isDateDisabled(new Date(2024, 6, 11), rules)).toBe(true);
+    });
+
+    it('returns false for a non-disabled date', () => {
+      expect(isDateDisabled(new Date(2024, 6, 12), rules)).toBe(false);
+    });
+
+    it('compares date-only, ignoring time', () => {
+      const dateWithTime = new Date(2024, 6, 11, 14, 30, 0);
+      expect(isDateDisabled(dateWithTime, rules)).toBe(true);
+    });
+
+    it('handles disabled dates that have non-zero time components', () => {
+      const rulesWithTime: DisabledRules = {
+        dates: [new Date(2024, 6, 11, 23, 59, 59)],
+        reason: 'Holiday',
+      };
+      expect(isDateDisabled(new Date(2024, 6, 11), rulesWithTime)).toBe(true);
+    });
+  });
+
+  describe('ranges', () => {
+    const rules: DisabledRules = {
+      ranges: [
+        { start: new Date(2024, 2, 29), end: new Date(2024, 3, 3) },
+        { start: new Date(2024, 11, 24), end: new Date(2024, 11, 26) },
+      ],
+      reason: 'Scheduled maintenance',
+    };
+
+    it('returns true for start of range (inclusive)', () => {
+      expect(isDateDisabled(new Date(2024, 2, 29), rules)).toBe(true);
+    });
+
+    it('returns true for end of range (inclusive)', () => {
+      expect(isDateDisabled(new Date(2024, 3, 3), rules)).toBe(true);
+    });
+
+    it('returns true for date within range', () => {
+      expect(isDateDisabled(new Date(2024, 2, 31), rules)).toBe(true);
+    });
+
+    it('returns false for date before range', () => {
+      expect(isDateDisabled(new Date(2024, 2, 28), rules)).toBe(false);
+    });
+
+    it('returns false for date after range', () => {
+      expect(isDateDisabled(new Date(2024, 3, 4), rules)).toBe(false);
+    });
+
+    it('handles second range', () => {
+      expect(isDateDisabled(new Date(2024, 11, 25), rules)).toBe(true);
+      expect(isDateDisabled(new Date(2024, 11, 27), rules)).toBe(false);
+    });
+
+    it('correctly checks a date with non-midnight time against a range', () => {
+      const dateWithTime = new Date(2024, 2, 31, 14, 30, 0);
+      expect(isDateDisabled(dateWithTime, rules)).toBe(true);
+    });
+
+    it('correctly excludes a date with non-midnight time outside a range', () => {
+      const dateWithTime = new Date(2024, 2, 28, 23, 59, 59);
+      expect(isDateDisabled(dateWithTime, rules)).toBe(false);
+    });
+  });
+
+  describe('combined rules (additive)', () => {
+    const rules: DisabledRules = {
+      weekdays: ['sat', 'sun'],
+      dates: [new Date(2024, 6, 15)], // Monday
+      ranges: [{ start: new Date(2024, 6, 22), end: new Date(2024, 6, 24) }],
+      reason: 'Multiple rules',
+    };
+
+    it('disables by weekday', () => {
+      // 2024-07-13 is Saturday
+      expect(isDateDisabled(new Date(2024, 6, 13), rules)).toBe(true);
+    });
+
+    it('disables by specific date', () => {
+      // 2024-07-15 is Monday but explicitly disabled
+      expect(isDateDisabled(new Date(2024, 6, 15), rules)).toBe(true);
+    });
+
+    it('disables by range', () => {
+      // 2024-07-23 is Tuesday but in range
+      expect(isDateDisabled(new Date(2024, 6, 23), rules)).toBe(true);
+    });
+
+    it('allows date not matching any rule', () => {
+      // 2024-07-16 is Tuesday, not in dates or ranges
+      expect(isDateDisabled(new Date(2024, 6, 16), rules)).toBe(false);
+    });
+  });
+
+  describe('edge cases', () => {
+    it('handles empty weekdays array', () => {
+      const rules: DisabledRules = { weekdays: [], reason: 'Empty' };
+      expect(isDateDisabled(new Date(2024, 6, 13), rules)).toBe(false);
+    });
+
+    it('handles empty dates array', () => {
+      const rules: DisabledRules = { dates: [], reason: 'Empty' };
+      expect(isDateDisabled(new Date(2024, 6, 13), rules)).toBe(false);
+    });
+
+    it('handles empty ranges array', () => {
+      const rules: DisabledRules = { ranges: [], reason: 'Empty' };
+      expect(isDateDisabled(new Date(2024, 6, 13), rules)).toBe(false);
+    });
+  });
+});

package/src/Calendar/_helpers/isDateDisabled/isDateDisabled.ts

@@ -0,0 +1,59 @@
+import type { DisabledRules, WeekDayType } from '../../Calendar.types';
+
+const DAY_INDEX_TO_WEEKDAY: Record<number, WeekDayType> = {
+  0: 'sun',
+  1: 'mon',
+  2: 'tue',
+  3: 'wed',
+  4: 'thu',
+  5: 'fri',
+  6: 'sat',
+};
+
+export function isDateDisabled(date: Date, disabledRules?: DisabledRules): boolean {
+  if (!disabledRules) return false;
+
+  if (disabledRules.weekdays?.length) {
+    const weekday = DAY_INDEX_TO_WEEKDAY[date.getDay()];
+    if (disabledRules.weekdays.includes(weekday)) return true;
+  }
+
+  if (disabledRules.dates?.length) {
+    const year = date.getFullYear();
+    const month = date.getMonth();
+    const day = date.getDate();
+    if (
+      disabledRules.dates.some(
+        (disabledDate) =>
+          disabledDate.getFullYear() === year &&
+          disabledDate.getMonth() === month &&
+          disabledDate.getDate() === day,
+      )
+    ) {
+      return true;
+    }
+  }
+
+  if (disabledRules.ranges?.length) {
+    const dateStart = date.getTime();
+    if (
+      disabledRules.ranges.some((range) => {
+        const rangeStart = new Date(
+          range.start.getFullYear(),
+          range.start.getMonth(),
+          range.start.getDate(),
+        ).getTime();
+        const rangeEnd = new Date(
+          range.end.getFullYear(),
+          range.end.getMonth(),
+          range.end.getDate(),
+        ).getTime();
+        return dateStart >= rangeStart && dateStart <= rangeEnd;
+      })
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+}

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

@@ -0,0 +1,118 @@
+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 (via `disabledRules`)
+
+Dates disabled via `disabledRules` remain focusable and keyboard-navigable. They 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"
+
+### 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: they can be clicked and the `aria-label` appends "not available". Arrow key navigation clamps at the boundary, so keyboard users cannot navigate into out-of-range cells — but they remain visible and clickable for pointer users.
+
+This distinction is intentional: `min`/`max` defines a hard boundary (the calendar simply doesn't extend beyond it), while `disabledRules` marks dates that exist but are unavailable (users should be able to discover them and understand why).
+
+## 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

@@ -1,22 +1,47 @@
 import { useState } from 'react';
 import { StoryObj } from '@storybook/react-webpack5';
-import { userEvent, within } from 'storybook/test';
+import { fn, userEvent, within } from 'storybook/test';
 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';
+import { action } from 'storybook/actions';
 
-/** Inline calendar for selecting a single date, with optional min/max bounds. */
 export default {
   component: Calendar,
   title: 'Forms/Calendar',
+  args: {
+    value: undefined,
+    min: undefined,
+    max: undefined,
+    monthFormat: undefined,
+    placeholder: undefined,
+    disabledRules: undefined,
+    onChange: fn(),
+    onDateFocus: fn(),
+  },
   argTypes: {
     monthFormat: { control: 'select', options: ['long', 'short'] },
     min: { control: 'date' },
     max: { control: 'date' },
+    disabledRules: {
+      control: false,
+      table: {
+        type: {
+          summary: 'DisabledRules',
+          detail: `{
+  weekdays?: ('mon'|'tue'|'wed'|'thu'|'fri'|'sat'|'sun')[]
+  dates?: Date[]
+  ranges?: { start: Date; end: Date }[]
+  reason: string  // required — shown in prompt, linked via aria-describedby
+}`,
+        },
+      },
+    },
   },
 };
 
@@ -30,12 +55,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)}
     />
   );
@@ -52,7 +82,13 @@ export const Basic: Story = {
         min={args.min ? new Date(args.min) : thePast}
         max={args.max ? new Date(args.max) : theFuture}
         value={value}
-        onChange={(v) => setValue(v)}
+        onDateFocus={(date, options) => {
+          action('onDateFocus')(date, options);
+        }}
+        onChange={(date) => {
+          action('onChange')(date);
+          setValue(date);
+        }}
       />
     );
   },
@@ -102,3 +138,101 @@ export const InsideModal: Story = {
     await userEvent.click(canvas.getByRole('button', { name: 'Open modal' }));
   },
 };
+
+/**
+ * Use `disabledRules` to disable specific weekdays, individual dates, or date ranges.
+ * Disabled dates remain focusable and keyboard-navigable — clicking or focusing one
+ * fires `onDateFocus` 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 4 December 2024 and 18 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({
+  render: function Render() {
+    const [value, setValue] = useState<Date | null>(new Date(2024, 11, 13));
+
+    return (
+      <Calendar
+        value={value}
+        min={new Date(2024, 11, 4)}
+        max={new Date(2025, 0, 18)}
+        disabledRules={{
+          weekdays: ['sat', 'sun'],
+          dates: [new Date(2024, 11, 10), new Date(2025, 0, 15)],
+          ranges: [{ start: new Date(2024, 11, 23), end: new Date(2024, 11, 27) }],
+          reason: 'Some dates are unavailable for this service.',
+        }}
+        onDateFocus={(date, { isEnabled }) => {
+          action('onDateFocus')(date, { isEnabled });
+        }}
+        onChange={(date) => {
+          action('onChange')(date);
+          setValue(date);
+        }}
+      />
+    );
+  },
+});
+
+/**
+ * When different disabled dates warrant different explanations, drive the `reason`
+ * dynamically from `onDateFocus`. 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({
+  render: function Render() {
+    const DEFAULT_REASON = 'Some dates are unavailable for this service.';
+    const min = new Date(2024, 11, 4);
+    const max = new Date(2025, 0, 18);
+    const maintenanceDays = [new Date(2024, 11, 10), new Date(2025, 0, 15)];
+    const [value, setValue] = useState<Date | null>(new Date(2024, 11, 13));
+    const [reason, setReason] = useState(DEFAULT_REASON);
+
+    function determineReason(date: Date, isEnabled: boolean): string {
+      if (isEnabled) return DEFAULT_REASON;
+      if (
+        maintenanceDays.some(
+          (maintenanceDay) => maintenanceDay.toDateString() === date.toDateString(),
+        )
+      ) {
+        return 'This date is a maintenance day.';
+      }
+      if (date.getDay() === 0 || date.getDay() === 6) {
+        return 'We do not operate on weekends.';
+      }
+      return 'This date is unavailable.';
+    }
+
+    return (
+      <Calendar
+        value={value}
+        min={min}
+        max={max}
+        disabledRules={{
+          weekdays: ['sat', 'sun'],
+          dates: maintenanceDays,
+          ranges: [{ start: new Date(2024, 11, 23), end: new Date(2024, 11, 27) }],
+          reason,
+        }}
+        onDateFocus={(date, { isEnabled }) => {
+          action('onDateFocus')(date, { isEnabled });
+          if (date) {
+            setReason(determineReason(date, isEnabled));
+          }
+        }}
+        onChange={(date) => {
+          action('onChange')(date);
+          setValue(date);
+        }}
+      />
+    );
+  },
+});

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