fix: Fix screen reader A11y issues and improve focus logic reliability

Author: NathanZlion

src/tutorial-panel/components/tutorial-list/index.tsx

@@ -28,7 +28,8 @@ interface TutorialListProps {
   onStartTutorial: HotspotContext['onStartTutorial'];
   i18nStrings: TutorialPanelProps['i18nStrings'];
   downloadUrl: TutorialPanelProps['downloadUrl'];
-  headerRef?: React.MutableRefObject<HTMLHeadingElement | null>;
+  headerRef?: (node: HTMLDivElement | null) => void;
+  headerId?: string;
 }
 
 export default function TutorialList({
@@ -38,6 +39,7 @@ export default function TutorialList({
   onStartTutorial,
   downloadUrl,
   headerRef,
+  headerId,
 }: TutorialListProps) {
   checkSafeUrl('TutorialPanel', downloadUrl);
 
@@ -47,8 +49,19 @@ export default function TutorialList({
     <>
       <InternalSpaceBetween size="s">
         <InternalSpaceBetween size="m">
-          <div ref={headerRef} tabIndex={-1}>
-            <InternalBox variant="h2" fontSize={isRefresh ? 'heading-m' : 'heading-l'} padding={{ bottom: 'n' }}>
+          <div
+            ref={headerRef}
+            tabIndex={-1}
+            role="region"
+            aria-labelledby={headerId}
+            className={styles['tutorial-header-region']}
+          >
+            <InternalBox
+              variant="h2"
+              fontSize={isRefresh ? 'heading-m' : 'heading-l'}
+              padding={{ bottom: 'n' }}
+              id={headerId}
+            >
               {i18nStrings.tutorialListTitle}
             </InternalBox>
           </div>

src/tutorial-panel/components/tutorial-list/styles.scss

@@ -17,6 +17,16 @@
   margin-inline: 0;
 }
 
+.tutorial-header-region {
+  @include focus-visible.when-visible {
+    @include styles.focus-highlight(0px);
+  }
+
+  &:focus {
+    outline: none;
+  }
+}
+
 .tutorial-box {
   @include styles.styles-reset;
   list-style: none;

src/tutorial-panel/index.tsx

@@ -1,9 +1,11 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 'use client';
-import React, { useContext, useRef } from 'react';
+import React, { useCallback, useContext, useRef } from 'react';
 import clsx from 'clsx';
 
+import { useUniqueId } from '@cloudscape-design/component-toolkit/internal';
+
 import { hotspotContext } from '../annotation-context/context';
 import { getBaseProps } from '../internal/base-component';
 import useBaseComponent from '../internal/hooks/use-base-component';
@@ -28,7 +30,26 @@ export default function TutorialPanel({
 
   const baseProps = getBaseProps(restProps);
   const context = useContext(hotspotContext);
-  const headerRef = useRef<HTMLHeadingElement>(null);
+
+  // should focus on the header (on exiting tutorial, we have to know and
+  // focus on header for accessiblity reasons)
+  const shouldFocusRef = useRef(false);
+  const headerId = useUniqueId('tutorial-header-');
+
+  const headerCallbackRef = useCallback((node: HTMLDivElement | null) => {
+    if (node && shouldFocusRef.current) {
+      node.focus({ preventScroll: true });
+      shouldFocusRef.current = false;
+    }
+  }, []);
+
+  const handleExitTutorial = useCallback(
+    (e: any) => {
+      shouldFocusRef.current = true;
+      context.onExitTutorial(e);
+    },
+    [context]
+  );
 
   return (
     <>
@@ -37,10 +58,7 @@ export default function TutorialPanel({
           <TutorialDetailView
             i18nStrings={i18nStrings}
             tutorial={context.currentTutorial}
-            onExitTutorial={e => {
-              context.onExitTutorial(e);
-              requestAnimationFrame(() => headerRef.current?.focus({ preventScroll: true }));
-            }}
+            onExitTutorial={handleExitTutorial}
             currentStepIndex={context.currentStepIndex}
             onFeedbackClick={onFeedbackClick}
           />
@@ -51,7 +69,8 @@ export default function TutorialPanel({
             loading={loading}
             onStartTutorial={context.onStartTutorial}
             downloadUrl={downloadUrl}
-            headerRef={headerRef}
+            headerRef={headerCallbackRef}
+            headerId={headerId}
           />
         )}
       </div>