@transferwise/components 46.131.2 → 46.132.1

package/src/common/liveRegion/LiveRegion.test.tsx

@@ -1,23 +1,43 @@
-import { render, screen } from '@testing-library/react';
-import { LiveRegion, LiveRegionProps } from './LiveRegion';
+import { act, render, screen } from '@testing-library/react';
+import { WDS_LIVE_REGION_DELAY_MS } from '../constants';
+import { LiveRegion, LiveRegionProps, resetLiveRegionAnnouncementQueue } from './LiveRegion';
 
 describe('LiveRegion', () => {
+  beforeEach(() => {
+    jest.useFakeTimers();
+    resetLiveRegionAnnouncementQueue();
+  });
+
+  afterEach(() => {
+    jest.clearAllTimers();
+    jest.useRealTimers();
+  });
+
   const renderLiveRegion = (props: Partial<LiveRegionProps> & Pick<LiveRegionProps, 'aria-live'>) =>
     render(<LiveRegion {...props}>{props.children ?? 'Live content'}</LiveRegion>);
 
+  const enableLiveRegion = (delay = WDS_LIVE_REGION_DELAY_MS) => {
+    act(() => {
+      jest.advanceTimersByTime(delay);
+    });
+  };
+
   describe('when aria-live is "polite"', () => {
     it('renders with role="status"', () => {
       renderLiveRegion({ 'aria-live': 'polite' });
+      enableLiveRegion();
       expect(screen.getByRole('status')).toBeInTheDocument();
     });
 
     it('sets aria-live="polite"', () => {
       renderLiveRegion({ 'aria-live': 'polite' });
+      enableLiveRegion();
       expect(screen.getByRole('status')).toHaveAttribute('aria-live', 'polite');
     });
 
     it('sets aria-atomic="true"', () => {
       renderLiveRegion({ 'aria-live': 'polite' });
+      enableLiveRegion();
       expect(screen.getByRole('status')).toHaveAttribute('aria-atomic', 'true');
     });
   });
@@ -25,32 +45,79 @@ describe('LiveRegion', () => {
   describe('when aria-live is "assertive"', () => {
     it('renders with role="alert"', () => {
       renderLiveRegion({ 'aria-live': 'assertive' });
+      enableLiveRegion();
       expect(screen.getByRole('alert')).toBeInTheDocument();
     });
 
     it('sets aria-live="assertive"', () => {
       renderLiveRegion({ 'aria-live': 'assertive' });
+      enableLiveRegion();
       expect(screen.getByRole('alert')).toHaveAttribute('aria-live', 'assertive');
     });
 
     it('sets aria-atomic="true"', () => {
       renderLiveRegion({ 'aria-live': 'assertive' });
+      enableLiveRegion();
       expect(screen.getByRole('alert')).toHaveAttribute('aria-atomic', 'true');
     });
   });
 
+  it('delays live-region activation before the configured timeout', () => {
+    renderLiveRegion({ 'aria-live': 'polite', children: 'Delayed content' });
+
+    const liveRegion = screen.getByRole('status');
+    expect(liveRegion).toBeInTheDocument();
+    expect(liveRegion.firstElementChild).toHaveAttribute('aria-hidden', 'true');
+
+    enableLiveRegion(WDS_LIVE_REGION_DELAY_MS - 1);
+    expect(liveRegion.firstElementChild).toHaveAttribute('aria-hidden', 'true');
+
+    enableLiveRegion(1);
+    expect(liveRegion.firstElementChild).not.toHaveAttribute('aria-hidden');
+    expect(liveRegion).toHaveTextContent('Delayed content');
+  });
+
+  it('queues multiple assertive regions so each one gets announced', () => {
+    render(
+      <>
+        <LiveRegion aria-live="assertive">First prompt</LiveRegion>
+        <LiveRegion aria-live="assertive">Second prompt</LiveRegion>
+      </>,
+    );
+
+    const liveRegions = screen.getAllByRole('alert');
+    expect(liveRegions).toHaveLength(2);
+    expect(liveRegions[0].firstElementChild).toHaveAttribute('aria-hidden', 'true');
+    expect(liveRegions[1].firstElementChild).toHaveAttribute('aria-hidden', 'true');
+
+    enableLiveRegion();
+    const firstEnabledLiveRegions = screen.getAllByRole('alert');
+    expect(firstEnabledLiveRegions[0].firstElementChild).not.toHaveAttribute('aria-hidden');
+    expect(firstEnabledLiveRegions[1].firstElementChild).toHaveAttribute('aria-hidden', 'true');
+    expect(firstEnabledLiveRegions[0]).toHaveTextContent('First prompt');
+
+    enableLiveRegion();
+    const secondEnabledLiveRegions = screen.getAllByRole('alert');
+    expect(secondEnabledLiveRegions[1].firstElementChild).not.toHaveAttribute('aria-hidden');
+    expect(secondEnabledLiveRegions[0]).toHaveTextContent('First prompt');
+    expect(secondEnabledLiveRegions[1]).toHaveTextContent('Second prompt');
+  });
+
   it('renders children', () => {
     renderLiveRegion({ 'aria-live': 'polite', children: 'Transfer sent' });
+    enableLiveRegion();
     expect(screen.getByText('Transfer sent')).toBeInTheDocument();
   });
 
   it('passes additional HTML attributes to the wrapper div', () => {
     renderLiveRegion({ 'aria-live': 'polite', className: 'custom' });
+    enableLiveRegion();
     expect(screen.getByRole('status')).toHaveClass('custom');
   });
 
   it('supports data-testid prop', () => {
     renderLiveRegion({ 'aria-live': 'polite', 'data-testid': 'live-region' });
+    enableLiveRegion();
     expect(screen.getByTestId('live-region')).toBeInTheDocument();
   });
 });

package/src/common/liveRegion/LiveRegion.tsx

@@ -1,11 +1,52 @@
+import { useEffect, useState } from 'react';
 import type { HTMLAttributes, ReactNode } from 'react';
 
-const ARIA_LIVE_ROLE_MAP = {
+import { WDS_LIVE_REGION_DELAY_MS } from '../constants';
+
+export type AriaLive = 'off' | 'polite' | 'assertive';
+
+type LivePoliteness = Exclude<AriaLive, 'off'>;
+
+const LIVE_REGION_ROLE_BY_POLITENESS: Record<LivePoliteness, 'status' | 'alert'> = {
   assertive: 'alert',
   polite: 'status',
-} as const;
+};
 
-export type AriaLive = 'off' | 'polite' | 'assertive';
+let nextPoliteAnnouncementAt = 0;
+let nextAssertiveAnnouncementAt = 0;
+
+const getNextAnnouncementAt = (politeness: LivePoliteness): number => {
+  if (politeness === 'polite') {
+    return nextPoliteAnnouncementAt;
+  }
+
+  return nextAssertiveAnnouncementAt;
+};
+
+const setNextAnnouncementAt = (politeness: LivePoliteness, value: number): void => {
+  if (politeness === 'polite') {
+    nextPoliteAnnouncementAt = value;
+    return;
+  }
+
+  nextAssertiveAnnouncementAt = value;
+};
+
+export const resetLiveRegionAnnouncementQueue = (): void => {
+  nextPoliteAnnouncementAt = 0;
+  nextAssertiveAnnouncementAt = 0;
+};
+
+const calcAnnouncementDelayMs = (politeness: LivePoliteness, now: number): number => {
+  return Math.max(now + WDS_LIVE_REGION_DELAY_MS, getNextAnnouncementAt(politeness)) - now;
+};
+
+const scheduleAnnouncement = (politeness: LivePoliteness): number => {
+  const now = Date.now();
+  const delayMs = calcAnnouncementDelayMs(politeness, now);
+  setNextAnnouncementAt(politeness, now + delayMs + WDS_LIVE_REGION_DELAY_MS);
+  return delayMs;
+};
 
 export interface LiveRegionProps extends Omit<
   HTMLAttributes<HTMLDivElement>,
@@ -15,6 +56,8 @@ export interface LiveRegionProps extends Omit<
    * Determines urgency: 'assertive' interrupts, 'polite' waits for idle, 'off' disables live region.
    */
   'aria-live': AriaLive;
+  /** Optional stable key that triggers a new announcement when it changes. */
+  announceOnChange?: string | number;
   /** Test ID for testing tools */
   'data-testid'?: string;
   children?: ReactNode;
@@ -25,25 +68,51 @@ export interface LiveRegionProps extends Omit<
  *
  * - `aria-live="polite"` → `role="status"`
  * - `aria-live="assertive"` → `role="alert"`
- * - `aria-live="off"` → no live region
+ * - `aria-live="off"` → no live region (renders children unwrapped)
  *
  * The `role` prop is intentionally excluded from the public API
  * to prevent mismatches between `aria-live` and `role`.
  */
-export const LiveRegion = ({ 'aria-live': ariaLive, children, ...props }: LiveRegionProps) => {
+export const LiveRegion = ({
+  'aria-live': ariaLive,
+  announceOnChange,
+  children,
+  className,
+  ...props
+}: LiveRegionProps) => {
+  const [shouldAnnounce, setShouldAnnounce] = useState(false);
+  const announcementTrigger =
+    announceOnChange ??
+    (typeof children === 'string' || typeof children === 'number' ? children : undefined);
+
+  useEffect(() => {
+    setShouldAnnounce(false);
+
+    if (ariaLive === 'off') {
+      return;
+    }
+
+    const timeoutId = window.setTimeout(
+      () => setShouldAnnounce(true),
+      scheduleAnnouncement(ariaLive),
+    );
+
+    return () => window.clearTimeout(timeoutId);
+  }, [ariaLive, announcementTrigger]);
+
   if (ariaLive === 'off') {
     return <>{children}</>;
   }
 
   return (
     <div
-      role={ARIA_LIVE_ROLE_MAP[ariaLive]}
+      role={LIVE_REGION_ROLE_BY_POLITENESS[ariaLive]}
       aria-live={ariaLive}
       aria-atomic="true"
-      style={{ display: 'contents' }}
+      className={`wds-LiveRegion ${className ?? ''}`}
       {...props}
     >
-      {children}
+      <div aria-hidden={shouldAnnounce ? undefined : 'true'}>{children}</div>
     </div>
   );
 };

package/src/display/Display.story.tsx

@@ -14,6 +14,8 @@ export const Basic = () => {
   const DE = 'äöüßabcdefghijklmnopqrstuvwxyz';
   const UA = 'Ми будуємо найбільш міжнародний рахунок у світі';
   const JA = 'ぁあぃいぅうぇえぉおかがきぎくぐけげこごさざしじすずせぜそぞただちぢっつづてで';
+  const ZN =
+    '的一是在不了有和人这中大为上个国我以要他时来用们生到作地于出就分对成会可主发年样能下过子说产种面而方后多定行学法所民得经十三之进着等部度家电力里如水化高自二理起小物现实加量都两体制机当使点从业本去最性性齉龘龘靐齉爩鱻猋驫麤籲爨癵驫鲙鬯鬻厵纛';
   return (
     <>
       <div lang="en">
@@ -77,7 +79,7 @@ export const Basic = () => {
       </div>
       <hr />
       <div lang="ja">
-        <h1>Everything eles, e.g 🇯🇵</h1>
+        <h1>Japanese</h1>
         Large
         <Display type={Typography.DISPLAY_LARGE}>{JA}</Display>
         <hr />
@@ -87,6 +89,18 @@ export const Basic = () => {
         Small
         <Display type={Typography.DISPLAY_SMALL}>{JA}</Display>
       </div>
+      <hr />
+      <div lang="zh-CN">
+        <h1>Simplified Chinese</h1>
+        Large
+        <Display type={Typography.DISPLAY_LARGE}>{ZN}</Display>
+        <hr />
+        Medium
+        <Display type={Typography.DISPLAY_MEDIUM}>{ZN}</Display>
+        <hr />
+        Small
+        <Display type={Typography.DISPLAY_SMALL}>{ZN}</Display>
+      </div>
     </>
   );
 };

package/src/expressiveMoneyInput/ExpressiveMoneyInput.story.tsx

@@ -55,7 +55,6 @@ export default {
   tags: ['contribution'],
   parameters: {
     docs: {
-      toc: true,
       canvas: {
         sourceState: 'hidden',
       },

package/src/header/Header.story.tsx

@@ -63,11 +63,6 @@ const meta: Meta<typeof Header> = {
   },
   tags: ['autodocs'],
   decorators: [withContainer],
-  parameters: {
-    docs: {
-      toc: true,
-    },
-  },
 };
 
 export default meta;

package/src/inputWithDisplayFormat/InputWithDisplayFormat.story.tsx

@@ -16,7 +16,6 @@ const meta: Meta<typeof InputWithDisplayFormat> = {
       </Field>
     );
   },
-
   args: {
     onFocus: fn(),
     onBlur: fn(),

package/src/inputs/SelectInput/_stories/SelectInput.docs.mdx

@@ -4,6 +4,60 @@ import { Meta } from '@storybook/addon-docs/blocks';
 
 # Accessibility
 
+## Keyboard navigation
+
+The component uses [Headless UI Listbox](https://headlessui.com/react/listbox) under the hood, which provides full keyboard support out of the box.
+
+<table>
+  <thead>
+    <tr>
+      <th>Key</th>
+      <th>Action</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>
+        <code>Tab</code> / click
+      </td>
+      <td>Focus the trigger button</td>
+    </tr>
+    <tr>
+      <td>
+        <code>Enter</code> / <code>Space</code>
+      </td>
+      <td>Open the listbox</td>
+    </tr>
+    <tr>
+      <td>
+        <code>↑</code> / <code>↓</code>
+      </td>
+      <td>Navigate options</td>
+    </tr>
+    <tr>
+      <td>
+        <code>Enter</code>
+      </td>
+      <td>Select the focused option</td>
+    </tr>
+    <tr>
+      <td>
+        <code>Escape</code> / <code>Tab</code>
+      </td>
+      <td>Close without selecting</td>
+    </tr>
+    <tr>
+      <td>
+        Typing (when <code>filterable</code>)
+      </td>
+      <td>
+        Narrows the list in the search input; <code>↑</code> / <code>↓</code> still navigate the
+        filtered results
+      </td>
+    </tr>
+  </tbody>
+</table>
+
 ## Labelling
 
 In order for the `<SelectInput />` to be considered accessible, it must be provided with a matching label, preferably via the <a href="/?path=/docs/field--docs">Field</a> component.
@@ -18,3 +72,11 @@ Additionally, the `listbox` container that holds all the options is also expecte
 3. Correctly paired input `<label />` text, ideally via the `Field` component.
 
 > Using option group heading is possible but complicated as we can have multiple groups, and those are not necessarily rendered consistently if search or virtualisation are enabled.
+
+## Custom triggers
+
+When using `renderTrigger`, the interactive element **must** be `SelectInputTriggerButton`. A plain `<button>` will not receive the ARIA attributes (`aria-expanded`, `aria-haspopup`, `aria-controls`) that the component manages, breaking screen reader announcements for the listbox state.
+
+## Multiple selection
+
+With `multiple`, selected items show a visible checkmark in the list. The trigger content is **consumer-controlled** via the `withinTrigger` boolean passed to `renderValue` — consumers are responsible for communicating the current selection accessibly inside the trigger (e.g. `"USD, EUR"` or `"3 currencies selected"`).