@transferwise/components 46.131.1 → 46.132.0

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"`).