[WIP/DO NOT MERGE]: update accessibility/keyboard navigation of ApiModal

src/components/ApiDocs/ApiComment.tsx

@@ -8,8 +8,10 @@ interface ApiCommentProps {
 
 export const ApiComment = ({ apiComment, codeBlock }: ApiCommentProps) => {
   if (!apiComment) return null;
-  const firstItem = apiComment[0];
-  if (!firstItem.text.replaceAll('-', '').trim()) {
+  const firstItem = apiComment[0]?.text
+    ? apiComment[0].text.replaceAll('-', '').trim()
+    : null;
+  if (!firstItem) {
     apiComment.shift();
   }
   const commentList = apiComment.map((snippet, idx) => {

src/components/ApiDocs/ApiModalProvider.tsx

@@ -1,10 +1,21 @@
-import { useState, createContext } from 'react';
+import { useState, createContext, useRef, RefObject } from 'react';
 import { LinkDataType } from './display/TypeLink';
 import { ApiModal } from './display/ApiModal';
 
-export const TypeContext = createContext({
+interface TypeContextInterface {
+  setModalData: (data: any) => void;
+  setModalTriggerRef: (ref: RefObject<HTMLButtonElement> | null) => void;
+  modalTriggerRef: RefObject<HTMLButtonElement> | null;
+  openModal: () => void;
+  addBreadCrumb: (data: any) => void;
+  setBC: (data: any) => void;
+}
+
+export const TypeContext = createContext<TypeContextInterface>({
   setModalData: (data) => data,
-  modalOpen: () => {},
+  setModalTriggerRef: (ref) => ref,
+  modalTriggerRef: null,
+  openModal: () => {},
   addBreadCrumb: (data) => data,
   setBC: (data) => data
 });
@@ -13,12 +24,26 @@ export const ApiModalProvider = ({ children }) => {
   const [modalData, setModalData] = useState({});
   const [showModal, setShowModal] = useState(false);
   const [breadCrumbs, setBreadCrumbs] = useState<LinkDataType[]>([]);
+  const [modalTriggerRef, setModalTriggerRef] =
+    useState<RefObject<HTMLButtonElement> | null>(null);
+
+  const modalRef = useRef<HTMLDialogElement>(null);
 
-  const modalOpen = () => {
+  const openModal = () => {
     setShowModal(true);
+    setTimeout(() => {
+      // Focus the dialog element after modal is set to open
+      modalRef?.current?.focus();
+    }, 0);
   };
   const closeModal = () => {
     setShowModal(false);
+    // Focus the original modal trigger button after dialog is closed,
+    // otherwise, focus will be lost on the page
+    setTimeout(() => {
+      modalTriggerRef?.current?.focus();
+      setModalTriggerRef(null);
+    }, 0);
   };
 
   const addBreadCrumb = (bc) => {
@@ -36,14 +61,17 @@ export const ApiModalProvider = ({ children }) => {
 
   const value = {
     setModalData,
-    modalOpen,
+    setModalTriggerRef,
+    modalTriggerRef,
+    openModal,
     addBreadCrumb,
     setBC
   };
 
   return (
     <TypeContext.Provider value={value}>
       <ApiModal
+        modalRef={modalRef}
         data={modalData}
         showModal={showModal}
         close={closeModal}

src/components/ApiDocs/display/ApiModal.tsx

@@ -1,3 +1,4 @@
+import { useEffect, useCallback } from 'react';
 import { Badge, View, Flex, Grid, Card, Button } from '@aws-amplify/ui-react';
 
 import { ApiModalBreadcrumbs } from './ApiModalBreadcrumbs';
@@ -8,29 +9,52 @@ import { LinkDataType, TypeLinkInterface } from './TypeLink';
 import references from '@/directory/apiReferences.json';
 
 interface ApiModalInterface {
-  data: any;
-  showModal?: boolean;
-  close: () => void;
   breadCrumbs: LinkDataType[];
   clearBC: () => void;
+  close: () => void;
+  data: any;
+  modalRef: React.RefObject<HTMLDialogElement>;
+  showModal?: boolean;
 }
 
 export const ApiModal = ({
-  data,
-  showModal = false,
-  close,
   breadCrumbs,
-  clearBC
+  clearBC,
+  close,
+  data,
+  modalRef,
+  showModal = false
 }: ApiModalInterface) => {
   if (data.type === 'reference') {
     data = references[data.target];
   }
   const description = data?.comment?.summary;
 
-  const closeModal = () => {
+  const closeModal = useCallback(() => {
     clearBC();
     close();
-  };
+  }, [clearBC, close]);
+
+  const handleEscape = useCallback(
+    (event: KeyboardEvent) => {
+      if (event.key === 'Escape') {
+        closeModal();
+      }
+    },
+    [closeModal]
+  );
+
+  // Use esc key to close modal
+  useEffect(() => {
+    const modal = modalRef.current;
+    if (showModal && modal) {
+      window.addEventListener('keyup', handleEscape);
+
+      return () => {
+        window.removeEventListener('keyup', handleEscape);
+      };
+    }
+  }, [showModal, handleEscape, modalRef]);
 
   let name = data.name;
   let typeParameters = data.typeArguments;
@@ -86,13 +110,21 @@ export const ApiModal = ({
 
   return (
     <View
-      aria-label={`${name} API Reference`}
       className={`api-modal-container${showModal ? ' api-modal-container--open' : ''}`}
     >
-      <Card as="dialog" className="api-modal" aria-modal="true">
+      <View className="api-modal-backdrop" onClick={closeModal}></View>
+      <Card
+        as="dialog"
+        aria-label={`${name} API Reference`}
+        className="api-modal"
+        aria-modal="true"
+        ref={modalRef}
+        tabIndex={-1}
+      >
         <Flex className="api-model__header">
           <ApiModalBreadcrumbs items={breadcrumbItems} />
           <Button
+            aria-label={`Close ${name} API Reference modal`}
             onClick={closeModal}
             size="small"
             variation="link"

src/components/ApiDocs/display/ApiModalBreadcrumbs.tsx

@@ -22,7 +22,7 @@ export const ApiModalBreadcrumbs = ({ items }: ApiModalBreadcrumbs) => {
       ref={navRef}
       aria-label="API Type breadcrumbs"
       className="api-modal__breadcrumbs"
-      tabIndex={0}
+      tabIndex={items && items.length > 1 ? 0 : -1}
     >
       {items
         ? items.map((item, index) => {

src/components/ApiDocs/display/TypeLink.tsx

@@ -1,4 +1,4 @@
-import { useContext } from 'react';
+import { useContext, useRef } from 'react';
 import { TypeContext } from '@/components/ApiDocs/ApiModalProvider';
 import { View } from '@aws-amplify/ui-react';
 
@@ -15,19 +15,30 @@ export interface TypeLinkInterface {
 }
 
 export const TypeLink = ({ linkData, breadCrumbs }: TypeLinkInterface) => {
-  const { setModalData, modalOpen, addBreadCrumb, setBC } =
-    useContext(TypeContext);
+  const {
+    setModalData,
+    openModal,
+    addBreadCrumb,
+    setBC,
+    setModalTriggerRef,
+    modalTriggerRef
+  } = useContext(TypeContext);
   const name = linkData.name;
   const className = `type-link kind-${linkData.kind}`;
+  const btnRef = useRef<HTMLButtonElement>(null);
 
   const onClickHandler = () => {
+    /** If the modal trigger button hasn't been set, set it here */
+    if (!modalTriggerRef) {
+      setModalTriggerRef(btnRef);
+    }
     setModalData(linkData);
     if (breadCrumbs) {
       setBC(breadCrumbs);
     } else {
       addBreadCrumb(linkData);
     }
-    modalOpen();
+    openModal();
   };
   if (
     linkData.type === 'intrinsic' ||
@@ -36,7 +47,7 @@ export const TypeLink = ({ linkData, breadCrumbs }: TypeLinkInterface) => {
     return <View as="span">{linkData.name}</View>;
   } else {
     return (
-      <button className={className} onClick={onClickHandler}>
+      <button className={className} ref={btnRef} onClick={onClickHandler}>
         {name}
       </button>
     );

src/styles/reference.scss

@@ -17,20 +17,33 @@
   left: 0;
   width: 100vw;
   height: 100vh;
-  background-color: rgba(0, 0, 0, 0.5);
+
   align-items: center;
   justify-content: center;
-  z-index: 99999;
+  z-index: 5;
   &--open {
     display: flex;
   }
 }
 
+.api-modal-backdrop {
+  position: fixed;
+  z-index: 1;
+  background-color: rgba(0, 0, 0, 0.5);
+  width: 100vw;
+  height: 100vh;
+}
+
 .api-modal {
+  z-index: 2;
   width: 800px;
   max-width: 90vw;
   max-height: 90vh;
   border-radius: var(--amplify-radii-medium);
+  &:focus-visible {
+    outline: 2px solid var(--amplify-colors-border-focus);
+    outline-offset: 2px;
+  }
 }
 
 .api-model__header {
@@ -44,6 +57,10 @@
   overflow: scroll;
   align-items: baseline;
   gap: 2px;
+  &:focus-visible {
+    outline: 2px solid var(--amplify-colors-border-focus);
+    outline-offset: 2px;
+  }
 }
 
 .api-modal__breadcrumbs__current {