feat(a11y): keyboard navigation and focus management

Focus hooks (useFocusTrap/useEscapeKey/useReturnFocus); Modal dialog + focus trap +
Escape + accessible close; accordion roving tabindex + arrow-key radiogroup; Checkbox
Space. ARIA labels localized (closeLabel, dialogLabel, paymentMethodsGroupLabel).
Reuse: shared AccessibilityUtils (focus/querySelectorAllWithin/activeElement +
focusableSelector) consumed by the focus hooks and accordion, removing duplicated externals.

Author: AbhishekChorotiya

src/Components/Accordion.res

@@ -6,6 +6,10 @@ let make = (
   ~checkoutEle: React.element,
   ~borderBottom: bool,
   ~borderRadiusStyle,
+  ~index: int=0,
+  ~isFocused: bool=true,
+  ~registerItemRef: (int, Nullable.t<Dom.element>) => unit=(_, _) => (),
+  ~onArrowNav: (int, int) => unit=(_, _) => (),
 ) => {
   let {themeObj, localeString} = Recoil.useRecoilValueFromAtom(configAtom)
   let {layout, customMethodNames} = Recoil.useRecoilValueFromAtom(optionAtom)
@@ -34,21 +38,40 @@ let make = (
     paymentOption.displayName,
     paymentOption.icon,
   )
+  let selected = selectedOption == paymentOption.paymentMethodName
   <div
     className={`AccordionItem flex flex-col`}
     style={
       minHeight: "60px",
       width: "-webkit-fill-available",
-      cursor: "pointer",
       marginBottom: layoutClass.spacedAccordionItems ? themeObj.spacingAccordionItem : "",
       border: `1px solid ${themeObj.borderColor}`,
       borderRadius: {borderRadiusStyle},
       borderBottomStyle: borderBottom ? "solid" : "hidden",
-    }
-    onClick={_ => setSelectedOption(_ => paymentOption.paymentMethodName)}>
+    }>
     <div
       className={`flex flex-row items-center ${accordionClass}`}
-      style={columnGap: themeObj.spacingUnit}>
+      role="radio"
+      ariaChecked={selected ? #"true" : #"false"}
+      tabIndex={isFocused ? 0 : -1}
+      ref={ReactDOM.Ref.callbackDomRef(el => registerItemRef(index, el))}
+      onKeyDown={event => {
+        let key = JsxEvent.Keyboard.key(event)
+        switch key {
+        | "ArrowDown" | "ArrowRight" =>
+          event->JsxEvent.Keyboard.preventDefault
+          onArrowNav(index, 1)
+        | "ArrowUp" | "ArrowLeft" =>
+          event->JsxEvent.Keyboard.preventDefault
+          onArrowNav(index, -1)
+        | "Enter" | " " =>
+          event->JsxEvent.Keyboard.preventDefault
+          setSelectedOption(_ => paymentOption.paymentMethodName)
+        | _ => ()
+        }
+      }}
+      style={columnGap: themeObj.spacingUnit, minHeight: "60px", cursor: "pointer"}
+      onClick={_ => setSelectedOption(_ => paymentOption.paymentMethodName)}>
       <RenderIf condition=layoutClass.radios>
         <Radio checked=radioClass />
       </RenderIf>

src/Components/AccordionContainer.res

@@ -1,4 +1,5 @@
 open RecoilAtoms
+
 module Loader = {
   @react.component
   let make = (~cardShimmerCount) => {
@@ -70,6 +71,16 @@ let make = (
   let layoutClass = CardUtils.getLayoutClass(layout)
   let (showMore, setShowMore) = React.useState(_ => false)
   let (selectedOption, setSelectedOption) = Recoil.useRecoilState(selectedOptionAtom)
+
+  // Roving-tabindex focus management for the radiogroup. The primary list and the
+  // "more" dropdown list are each treated as their own roving group: arrow keys move
+  // DOM focus within the rendered list and wrap at its ends. `-1` means "nothing has
+  // been focused yet", in which case the roving-tabbable item falls back to the
+  // selected item (else the first item).
+  let (cardFocusedIndex, setCardFocusedIndex) = React.useState(_ => -1)
+  let (dropDownFocusedIndex, setDropDownFocusedIndex) = React.useState(_ => -1)
+  let cardItemRefs = React.useRef([])
+  let dropDownItemRefs = React.useRef([])
   let paymentMethodListValue = Recoil.useRecoilValueFromAtom(PaymentUtils.paymentMethodListValue)
   let {
     displayInSeparateScreen,
@@ -140,6 +151,44 @@ let make = (
     }
   }
 
+  // Store/clear an item's DOM element in a list's ref registry at its index.
+  let registerItemRef = (refs: React.ref<array<Nullable.t<Dom.element>>>, index, el) => {
+    while refs.current->Array.length <= index {
+      refs.current->Array.push(Nullable.null)->ignore
+    }
+    refs.current[index] = el
+  }
+
+  // The roving-tabbable index for a list: the explicitly-focused item if any,
+  // otherwise the selected item, otherwise the first item.
+  let getRovingIndex = (focusedIndex, list: array<PaymentMethodsRecord.paymentFieldsInfo>) =>
+    if focusedIndex >= 0 {
+      focusedIndex
+    } else {
+      switch list->Array.findIndex(o => o.paymentMethodName == selectedOption) {
+      | -1 => 0
+      | selectedIndex => selectedIndex
+      }
+    }
+
+  // Move DOM focus within a single list (wrapping at the ends) and update its
+  // focused-index state so the roving tabindex follows.
+  let moveFocus = (
+    refs: React.ref<array<Nullable.t<Dom.element>>>,
+    setFocusedIndex,
+    length,
+    index,
+    delta,
+  ) =>
+    if length > 0 {
+      let nextIndex = mod(mod(index + delta, length) + length, length)
+      setFocusedIndex(_ => nextIndex)
+      refs.current
+      ->Array.get(nextIndex)
+      ->Option.flatMap(Nullable.toOption)
+      ->Option.forEach(el => el->AccessibilityUtils.focus)
+    }
+
   React.useEffect0(() => {
     let shouldAutoOpenSavedMethods =
       !layoutClass.savedMethodCustomization.defaultCollapsed &&
@@ -155,6 +204,8 @@ let make = (
   <div className="w-full">
     <div
       className="AccordionContainer flex flex-col overflow-auto no-scrollbar"
+      role="radiogroup"
+      ariaLabel={localeString.paymentMethodsGroupLabel}
       style={
         marginTop: themeObj.spacingAccordionItem,
         width: "-webkit-fill-available",
@@ -173,6 +224,17 @@ let make = (
           borderBottom={(!showMore &&
           i == cardOptionDetails->Array.length - 1 &&
           !layoutClass.spacedAccordionItems) || layoutClass.spacedAccordionItems}
+          index=i
+          isFocused={i == getRovingIndex(cardFocusedIndex, cardOptionDetails)}
+          registerItemRef={registerItemRef(cardItemRefs, ...)}
+          onArrowNav={(index, delta) =>
+            moveFocus(
+              cardItemRefs,
+              setCardFocusedIndex,
+              cardOptionDetails->Array.length,
+              index,
+              delta,
+            )}
         />
       })
       ->React.array}
@@ -190,6 +252,17 @@ let make = (
             borderRadiusStyle={borderRadiusStyle}
             borderBottom={(i == dropDownOptionsDetails->Array.length - 1 &&
               !layoutClass.spacedAccordionItems) || layoutClass.spacedAccordionItems}
+            index=i
+            isFocused={i == getRovingIndex(dropDownFocusedIndex, dropDownOptionsDetails)}
+            registerItemRef={registerItemRef(dropDownItemRefs, ...)}
+            onArrowNav={(index, delta) =>
+              moveFocus(
+                dropDownItemRefs,
+                setDropDownFocusedIndex,
+                dropDownOptionsDetails->Array.length,
+                index,
+                delta,
+              )}
           />
         })
         ->React.array}
@@ -198,6 +271,9 @@ let make = (
     <RenderIf condition={!showMore && dropDownOptionsDetails->Array.length > 0}>
       <button
         className="AccordionMore flex overflow-auto no-scrollbar"
+        type_="button"
+        ariaExpanded=false
+        ariaLabel={localeString.morePaymentMethodsLabel}
         onClick={_ => setShowMore(_ => !showMore)}
         style={
           borderRadius: themeObj.borderRadius,

src/Components/Checkbox.res

@@ -62,6 +62,10 @@ let make = (~isChecked, ~onChange, ~label, ~ariaLabelChecked="", ~ariaLabelUnche
       let keyCode = JsxEvent.Keyboard.keyCode(event)
       if key == "Enter" || keyCode == 13 {
         onChange(!isChecked)
+      } else if key == " " {
+        // WAI-ARIA checkbox idiom: Space toggles. preventDefault stops page scroll.
+        event->JsxEvent.Keyboard.preventDefault
+        onChange(!isChecked)
       }
     }}
     role="checkbox"

src/Components/FullScreenPortal.res

@@ -2,6 +2,27 @@ open Utils
 @val @scope(("window", "parent", "frames", `"fullscreen"`, "document"))
 external getElementById: string => Dom.element = "getElementById"
 
+/*
+ * Accessibility note (Task 12 — keyboard-navigation gap closure):
+ *
+ * This component is a thin portal: it renders `children` into the REMOTE
+ * `#fullscreen` iframe document via `ReactDOM.createPortal`. The only consumers
+ * (ACHBankDebit / BecsBankDebit) portal a `<BankDebitModal>`, whose content is
+ * the shared `Modal` component. `Modal` already provides the full dialog
+ * contract: `role="dialog"` + `ariaModal=true` + an accessible name, plus
+ * `AccessibilityHooks.useReturnFocus` / `useFocusTrap` / `useEscapeKey`
+ * (Escape -> close path that posts `("fullscreen", false)` to the parent).
+ *
+ * Therefore NO dialog semantics, focus-into-dialog, or Escape handling are added
+ * here: wrapping the portalled `Modal` in a second `role="dialog"`/`ariaModal`
+ * container would create a nested/duplicate dialog (a screen-reader regression),
+ * not an additive landmark. The genuine dismissal path lives on `Modal` and must
+ * stay the single source of truth so the bank-debit flow is not corrupted.
+ *
+ * Cross-document note: `AccessibilityHooks` derive their keydown target and
+ * active element from the rendered modal container's owner document, so the same
+ * modal contract applies when content is portalled into the fullscreen iframe.
+ */
 @react.component
 let make = (~children) => {
   let (fullScreenIframeNode, setFullScreenIframeNode) = React.useState(() => Nullable.null)

src/Components/Modal.res

@@ -12,10 +12,12 @@ let make = (
   ~loader=false,
   ~showClose=true,
   ~testMode=true,
+  ~ariaLabel=?,
   ~setOpenModal,
   ~openModal,
 ) => {
-  let {themeObj} = Recoil.useRecoilValueFromAtom(RecoilAtoms.configAtom)
+  let {themeObj, localeString} = Recoil.useRecoilValueFromAtom(RecoilAtoms.configAtom)
+  let modalAriaLabel = ariaLabel->Option.getOr(localeString.dialogLabel)
   let closeModal = () => {
     setOpenModal(_ => false)
     switch closeCallback {
@@ -31,6 +33,27 @@ let make = (
     None
   }, [loader])
 
+  // Ref on the modal content container, used for focus management (focus trap +
+  // moving focus into the dialog on open).
+  let containerRef = React.useRef(Nullable.null)
+
+  // Accessibility: return focus to the trigger on close, trap focus while open,
+  // and close on Escape — preserving all existing close behaviour.
+  AccessibilityHooks.useReturnFocus(~active=openModal, ~containerRef)
+  AccessibilityHooks.useFocusTrap(~active=openModal, ~containerRef)
+  AccessibilityHooks.useEscapeKey(~enabled=openModal, ~onEscape=closeModal, ~containerRef)
+
+  // On open, move focus to the first focusable element inside the dialog.
+  React.useEffect(() => {
+    if openModal {
+      switch AccessibilityHooks.getFocusableElements(containerRef)->Array.get(0) {
+      | Some(el) => el->AccessibilityUtils.focus
+      | None => ()
+      }
+    }
+    None
+  }, [openModal])
+
   let loaderVisibility = loader ? "visible" : "hidden"
   let contentVisibility = React.useMemo(() => {
     !openModal ? "hidden" : "visible"
@@ -51,6 +74,10 @@ let make = (
     }>
     {loaderUI}
     {<div
+      ref={ReactDOM.Ref.domRef(containerRef)}
+      role="dialog"
+      ariaModal=true
+      ariaLabel={modalAriaLabel}
       className={`w-full h-full sm:h-auto sm:w-[55%] md:w-[45%] lg:w-[35%] xl:w-[32%] 2xl:w-[27%]  m-auto bg-white flex flex-col justify-start sm:justify-center px-5 pb-5 md:pb-6 pt-4 md:pt-7 rounded-none sm:rounded-md relative overflow-scroll ${animate}`}
       style={
         transition: "opacity .35s ease .1s,transform .35s ease .1s,-webkit-transform .35s ease .1s",
@@ -69,11 +96,13 @@ let make = (
           </div>
         </RenderIf>
         <RenderIf condition=showClose>
-          <div
+          <button
+            type_="button"
             className="p-4 flex justify-end self-end mb-4 cursor-pointer"
-            onClick={_ => closeModal()}>
+            onClick={_ => closeModal()}
+            ariaLabel={localeString.closeLabel}>
             <Icon name="cross" size=23 />
-          </div>
+          </button>
         </RenderIf>
       </div>
       <div className={`mt-12 sm:${marginTop}`}> children </div>