@transferwise/components 0.0.0-experimental-b77dac7 → 0.0.0-experimental-fa3aa98

package/src/Calendar/YearCalendar/Table/YearCalendarTable.tsx

@@ -2,10 +2,11 @@ import { formatDate } from '@transferwise/formatting';
 import { useIntl } from 'react-intl';
 
 import { getFocusableTime } from '../../GetFocusableTime/GetFocusableTime';
-import TableLink from '../../tableLink';
+import TableLink from '../../TableLink';
 
 interface YearCalendarTableProps {
   selectedDate: Date | null;
+  focusedDate?: Date | null;
   min: Date | null;
   max: Date | null;
   viewYear: number;
@@ -19,6 +20,7 @@ const YEAR_ONLY_FORMAT: Intl.DateTimeFormatOptions = { year: 'numeric' };
 
 const YearCalendarTable = ({
   selectedDate,
+  focusedDate,
   min,
   max,
   viewYear,
@@ -34,7 +36,8 @@ const YearCalendarTable = ({
         type="year"
         title={formatDate(new Date(year, 0), locale, YEAR_ONLY_FORMAT)}
         active={isActive(year)}
-        disabled={isDisabled(year)}
+        outOfRange={isDisabled(year)}
+        disabled={false}
         today={isThisYear(year)}
         autofocus={autofocusYear === year}
         onClick={onSelect}
@@ -46,6 +49,10 @@ const YearCalendarTable = ({
     return !!(year === selectedDate?.getFullYear());
   };
 
+  const isFocused = (year: number) => {
+    return !!(year === focusedDate?.getFullYear());
+  };
+
   const isThisYear = (year: number) => {
     return year === new Date().getFullYear();
   };
@@ -56,7 +63,12 @@ const YearCalendarTable = ({
 
   const autofocusYear = (() => {
     const years = Array.from({ length: ROWS * COLS }, (_, index) => startYear + index);
-    return getFocusableTime({ isActive, isNow: isThisYear, isDisabled, timeSpan: years });
+    return getFocusableTime({
+      isActive: isFocused,
+      isNow: isThisYear,
+      isDisabled,
+      timeSpan: years,
+    });
   })();
 
   return (

package/src/Calendar/YearCalendar/YearCalendar.tsx

@@ -8,6 +8,7 @@ import YearCalendarTable from './Table';
 
 interface YearCalendarProps extends WrappedComponentProps {
   selectedDate: Date | null;
+  focusedDate?: Date | null;
   min: Date | null;
   max: Date | null;
   viewYear: number;
@@ -33,21 +34,29 @@ class YearCalendar extends PureComponent<YearCalendarProps> {
   render() {
     const {
       selectedDate,
+      focusedDate,
       min,
       max,
       viewYear,
       placeholder,
       intl: { formatMessage },
     } = this.props;
+    const startYear = viewYear - (viewYear % 20);
+    const isPreviousDisabled = !!(min && startYear - 1 < min.getFullYear());
+    const isNextDisabled = !!(max && startYear + 20 > max.getFullYear());
+
     return (
       <>
         <DateHeader
           dateMode={formatMessage(messages.twentyYears)}
+          isPreviousDisabled={isPreviousDisabled}
+          isNextDisabled={isNextDisabled}
           onPreviousClick={this.selectPreviousYears}
           onNextClick={this.selectNextYears}
         />
         <YearCalendarTable
           selectedDate={selectedDate}
+          focusedDate={focusedDate}
           min={min}
           max={max}
           viewYear={viewYear}

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,74 @@
+import type { Meta, StoryObj } from '@storybook/react-webpack5';
+import { expect, within , userEvent } from 'storybook/test';
+
+import Calendar from '../Calendar';
+
+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.toBeDisabled();
+
+    // Adjacent years outside range are disabled
+    await expect(canvas.getByRole('button', { name: /^2023.*not available/iu })).toBeDisabled();
+    await expect(canvas.getByRole('button', { name: /^2025.*not available/iu })).toBeDisabled();
+
+    // 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.toBeDisabled();
+
+    // Boundary months (min=Mar, max=Oct) are enabled
+    await expect(
+      canvas.getByRole('button', { name: /^Mar(?!.*not available)/iu }),
+    ).not.toBeDisabled();
+    await expect(
+      canvas.getByRole('button', { name: /^Oct(?!.*not available)/iu }),
+    ).not.toBeDisabled();
+
+    // Months outside range are disabled
+    await expect(canvas.getByRole('button', { name: /^Feb.*not available/iu })).toBeDisabled();
+    await expect(canvas.getByRole('button', { name: /^Nov.*not available/iu })).toBeDisabled();
+
+    // 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();
+  },
+};

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