fix: Restore focus to tutorial panel on dismiss (#4167)

Author: NathanZlion

src/tutorial-panel/__tests__/tutorial-panel.test.tsx

@@ -293,5 +293,41 @@ describe('URL sanitization', () => {
         'LEARN_MORE_ABOUT_TUTORIA'
       );
     });
+
+    test('focus returns to panel when exiting tutorial', () => {
+      const mockFocus = jest.fn();
+      const tutorials = getTutorials();
+      const originalFocus = HTMLElement.prototype.focus;
+      HTMLElement.prototype.focus = mockFocus;
+
+      const { container, context, rerender } = renderTutorialPanelWithContext(
+        {},
+        {
+          currentTutorial: tutorials[0],
+        }
+      );
+
+      const wrapper = createWrapper(container).findTutorialPanel()!;
+      wrapper.findDismissButton()!.click();
+      expect(context.onExitTutorial).toHaveBeenCalledTimes(1);
+      rerender(
+        <HotspotContext.Provider value={{ ...context, currentTutorial: null }}>
+          <TutorialPanel
+            i18nStrings={i18nStrings}
+            downloadUrl="DOWNLOAD_URL"
+            onFeedbackClick={() => {}}
+            tutorials={tutorials}
+          />
+        </HotspotContext.Provider>
+      );
+
+      const wrapperAfterExit = createWrapper(container).findTutorialPanel()!;
+      const panelElement = wrapperAfterExit.getElement();
+
+      expect(mockFocus).toHaveBeenCalledTimes(1);
+      expect(mockFocus.mock.instances[0]).toBe(panelElement);
+
+      HTMLElement.prototype.focus = originalFocus;
+    });
   });
 });

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

@@ -28,6 +28,7 @@ interface TutorialListProps {
   onStartTutorial: HotspotContext['onStartTutorial'];
   i18nStrings: TutorialPanelProps['i18nStrings'];
   downloadUrl: TutorialPanelProps['downloadUrl'];
+  headingId?: string;
 }
 
 export default function TutorialList({
@@ -36,6 +37,7 @@ export default function TutorialList({
   loading = false,
   onStartTutorial,
   downloadUrl,
+  headingId,
 }: TutorialListProps) {
   checkSafeUrl('TutorialPanel', downloadUrl);
 
@@ -45,7 +47,12 @@ export default function TutorialList({
     <>
       <InternalSpaceBetween size="s">
         <InternalSpaceBetween size="m">
-          <InternalBox variant="h2" fontSize={isRefresh ? 'heading-m' : 'heading-l'} padding={{ bottom: 'n' }}>
+          <InternalBox
+            variant="h2"
+            fontSize={isRefresh ? 'heading-m' : 'heading-l'}
+            padding={{ bottom: 'n' }}
+            id={headingId}
+          >
             {i18nStrings.tutorialListTitle}
           </InternalBox>
           <InternalBox variant="p" color="text-body-secondary" padding="n">

src/tutorial-panel/index.tsx

@@ -1,11 +1,14 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 'use client';
-import React, { useContext } from 'react';
+import React, { useContext, useRef } from 'react';
 import clsx from 'clsx';
 
+import { useMergeRefs, useUniqueId } from '@cloudscape-design/component-toolkit/internal';
+
 import { hotspotContext } from '../annotation-context/context';
 import { getBaseProps } from '../internal/base-component';
+import { NonCancelableCustomEvent } from '../internal/events';
 import useBaseComponent from '../internal/hooks/use-base-component';
 import { applyDisplayName } from '../internal/utils/apply-display-name';
 import TutorialDetailView from './components/tutorial-detail-view';
@@ -25,18 +28,38 @@ export default function TutorialPanel({
   ...restProps
 }: TutorialPanelProps) {
   const { __internalRootRef } = useBaseComponent('TutorialPanel');
+  const panelRef = useRef<HTMLDivElement>(null);
+  const headingId = useUniqueId();
 
   const baseProps = getBaseProps(restProps);
   const context = useContext(hotspotContext);
 
+  function handleExitTutorial(event: NonCancelableCustomEvent<TutorialPanelProps.TutorialDetail>) {
+    context.onExitTutorial(event);
+    panelRef.current?.focus();
+  }
+
+  const mergedRef = useMergeRefs(panelRef, __internalRootRef);
+
   return (
     <>
-      <div {...baseProps} className={clsx(baseProps.className, styles['tutorial-panel'])} ref={__internalRootRef}>
+      <div
+        {...baseProps}
+        className={clsx(baseProps.className, styles['tutorial-panel'])}
+        ref={mergedRef}
+        tabIndex={-1}
+        // Adding attributes conditionally since we don't want to point to
+        // a non existent header in the aria-labelledby
+        {...(!context.currentTutorial && {
+          role: 'region',
+          'aria-labelledby': headingId,
+        })}
+      >
         {context.currentTutorial ? (
           <TutorialDetailView
             i18nStrings={i18nStrings}
             tutorial={context.currentTutorial}
-            onExitTutorial={context.onExitTutorial}
+            onExitTutorial={handleExitTutorial}
             currentStepIndex={context.currentStepIndex}
             onFeedbackClick={onFeedbackClick}
           />
@@ -47,6 +70,7 @@ export default function TutorialPanel({
             loading={loading}
             onStartTutorial={context.onStartTutorial}
             downloadUrl={downloadUrl}
+            headingId={headingId}
           />
         )}
       </div>

src/tutorial-panel/styles.scss

@@ -5,10 +5,18 @@
 
 @use '../internal/styles/tokens' as awsui;
 @use '../internal/styles' as styles;
+@use '@cloudscape-design/component-toolkit/internal/focus-visible' as focus-visible;
 
 .tutorial-panel {
   @include styles.styles-reset;
   padding-block-start: 0;
   padding-block-end: awsui.$space-m;
   padding-inline: awsui.$space-l;
+
+  &:focus {
+    outline: none;
+  }
+  @include focus-visible.when-visible {
+    @include styles.focus-highlight(0px);
+  }
 }