From 88425759c93f85ae71ff3082054f7cddfbec47aa Mon Sep 17 00:00:00 2001
From: Tamas Kovacs <tamas.kovacs@instructure.com>
Date: Thu, 23 Jan 2025 14:24:27 +0100
Subject: [PATCH] chore: add 'Skip to main content' button to the main page

Closes: INSTUI-4240
chore: add 'Skip to main content' button to the main page
---
 packages/__docs__/src/App/index.tsx       | 152 ++++++++++++++++++----
 packages/__docs__/src/App/props.ts        |   1 +
 packages/__docs__/src/App/styles.ts       |  15 +++
 packages/__docs__/src/Hero/index.tsx      |  20 ++-
 packages/__docs__/src/Nav/index.tsx       |  43 +++++-
 packages/__docs__/src/NavToggle/index.tsx |  14 +-
 packages/__docs__/src/NavToggle/props.ts  |  13 +-
 7 files changed, 223 insertions(+), 35 deletions(-)

diff --git a/packages/__docs__/src/App/index.tsx b/packages/__docs__/src/App/index.tsx
index 594d375d4b..66b8066c31 100644
--- a/packages/__docs__/src/App/index.tsx
+++ b/packages/__docs__/src/App/index.tsx
@@ -28,7 +28,8 @@ import {
   createContext,
   LegacyRef,
   ReactElement,
-  SyntheticEvent
+  SyntheticEvent,
+  createRef
 } from 'react'
 
 import { Alert } from '@instructure/ui-alerts'
@@ -106,6 +107,10 @@ class App extends Component<AppProps, AppState> {
   _mediaQueryListener?: ReturnType<typeof addMediaQueryMatchListener>
   _defaultDocumentTitle?: string
   _controller?: AbortController
+  _heroRef: React.RefObject<Hero>
+  _navRef: React.RefObject<Nav>
+  _skipToMainButtonRef?: HTMLElement
+  _mainContentRef?: HTMLElement
 
   constructor(props: AppProps) {
     super(props)
@@ -127,6 +132,9 @@ class App extends Component<AppProps, AppState> {
       versionsData: undefined,
       iconsData: null
     }
+
+    this._heroRef = createRef()
+    this._navRef = createRef()
   }
 
   fetchDocumentData = async (docId: string) => {
@@ -151,6 +159,16 @@ class App extends Component<AppProps, AppState> {
     return this.setState({ versionsData })
   }
 
+  mainContentRef = (el: Element | null) => {
+    this._mainContentRef = el as HTMLElement
+  }
+
+  focusContent = () => {
+    if (this._mainContentRef) {
+      this._mainContentRef.focus()
+    }
+  }
+
   scrollToElement() {
     const [_page, id] = this.getPathInfo()
 
@@ -192,6 +210,7 @@ class App extends Component<AppProps, AppState> {
     const errorHandler = (error: Error) => {
       logError(error.name === 'AbortError', error.message)
     }
+    document.addEventListener('keydown', this.handleTabKey)
 
     fetch('icons-data.json', { signal })
       .then((response) => response.json())
@@ -285,7 +304,9 @@ class App extends Component<AppProps, AppState> {
   }
 
   handleMenuOpen = () => {
-    this.setState({ showMenu: true })
+    this.setState({ showMenu: true }, () => {
+      this._navRef.current?.focusTextInput()
+    })
   }
 
   handleMenuClose = () => {
@@ -316,6 +337,33 @@ class App extends Component<AppProps, AppState> {
     }
   }
 
+  focusMainContent = () => {
+    if (this._heroRef?.current?.focusMainContent) {
+      this._heroRef.current.focusMainContent()
+    } else if (this._mainContentRef?.focus) {
+      this._mainContentRef.focus()
+    }
+  }
+
+  handleTabKey = (event: KeyboardEvent) => {
+    if (event.key === 'Tab') {
+      if (document.activeElement === document.body) {
+        event.preventDefault()
+        this.focusSkipToMainButton()
+      }
+    }
+  }
+
+  skipToMainButtonRef = (el: Element | null) => {
+    this._skipToMainButtonRef = el as HTMLElement
+  }
+
+  focusSkipToMainButton = () => {
+    if (this._skipToMainButtonRef) {
+      this._skipToMainButtonRef.focus()
+    }
+  }
+
   renderThemeSelect() {
     const themeKeys = Object.keys(this.state.docsData!.themes)
     const smallScreen = this.state.layout === 'small'
@@ -443,18 +491,24 @@ class App extends Component<AppProps, AppState> {
         }
       >
         {this.renderThemeSelect()}
-        <Section id={currentData.id} heading={heading}>
-          <Document
-            doc={{
-              ...currentData,
-              legacyGitBranch
-            }}
-            description={currentData.description}
-            themeVariables={themeVariables}
-            repository={repository}
-            layout={layout}
-          />
-        </Section>
+        <View
+          elementRef={this.mainContentRef}
+          tabIndex={0}
+          aria-label="main content"
+        >
+          <Section id={currentData.id} heading={heading}>
+            <Document
+              doc={{
+                ...currentData,
+                legacyGitBranch
+              }}
+              description={currentData.description}
+              themeVariables={themeVariables}
+              repository={repository}
+              layout={layout}
+            />
+          </Section>
+        </View>
       </View>
     )
     return this.renderWrappedContent(documentContent)
@@ -487,6 +541,7 @@ class App extends Component<AppProps, AppState> {
           repository={library.repository}
           version={library.version}
           layout={layout}
+          ref={this._heroRef}
         />
       </InstUISettingsProvider>
     )
@@ -552,15 +607,48 @@ class App extends Component<AppProps, AppState> {
       return this.renderHero()
     }
     if (key === 'CHANGELOG') {
-      return this.renderChangeLog()
+      return (
+        <View
+          elementRef={this.mainContentRef}
+          tabIndex={0}
+          aria-label="changelog page main content"
+        >
+          {this.renderChangeLog()}
+        </View>
+      )
     } else if (key === 'icons') {
-      return this.renderIcons(key)
+      return (
+        <View
+          elementRef={this.mainContentRef}
+          tabIndex={0}
+          aria-label="icons page main content"
+          as={'div'}
+        >
+          {this.renderIcons(key)}
+        </View>
+      )
     } else if (theme) {
-      return this.renderTheme(key)
+      return (
+        <View
+          elementRef={this.mainContentRef}
+          tabIndex={0}
+          aria-label="theme page main content"
+        >
+          {this.renderTheme(key)}
+        </View>
+      )
     } else if (doc) {
       return this.renderDocument(key!, repository)
     } else {
-      return this.renderError()
+      return (
+        <View
+          elementRef={this.mainContentRef}
+          tabIndex={0}
+          aria-label="error page main content"
+        >
+          {this.renderError()}
+        </View>
+      )
     }
   }
 
@@ -613,13 +701,7 @@ class App extends Component<AppProps, AppState> {
               shape="circle"
               color="secondary"
               size="medium"
-              aria-expanded={true}
-              ref={(button) => {
-                if (button) {
-                  button.focus()
-                }
-              }}
-            />
+              aria-expanded={true} />
           </InstUISettingsProvider>
         </View>
 
@@ -634,6 +716,7 @@ class App extends Component<AppProps, AppState> {
           sections={this.state.docsData!.sections}
           docs={this.state.docsData!.docs}
           themes={this.state.docsData!.themes}
+          ref={this._navRef}
         />
       </View>
     )
@@ -692,6 +775,24 @@ class App extends Component<AppProps, AppState> {
     ) : null
   }
 
+  renderSkipToMainButton = () => {
+    return (
+      <View
+        as={'button'}
+        onClick={this.focusMainContent}
+        tabIndex={0}
+        css={this.props.styles?.skipToMainButton}
+        borderRadius="small"
+        display="inline-block"
+        padding="small"
+        background="primary"
+        elementRef={this.skipToMainButtonRef}
+      >
+        Skip to main content
+      </View>
+    )
+  }
+
   render() {
     const key = this.state.key
     const { showMenu, layout, docsData, iconsData } = this.state
@@ -712,6 +813,7 @@ class App extends Component<AppProps, AppState> {
           {showMenu && layout === 'small' && (
             <Mask onClick={this.handleMenuClose} />
           )}
+          {this.renderSkipToMainButton()}
           {this.renderNavigation()}
           <div
             css={this.props.styles?.content}
diff --git a/packages/__docs__/src/App/props.ts b/packages/__docs__/src/App/props.ts
index 55923403e3..c3de7202b2 100644
--- a/packages/__docs__/src/App/props.ts
+++ b/packages/__docs__/src/App/props.ts
@@ -51,6 +51,7 @@ type AppStyle = ComponentStyle<
   | 'hamburger'
   | 'inlineNavigation'
   | 'globalStyles'
+  | 'skipToMainButton'
 >
 
 type AppTheme = {
diff --git a/packages/__docs__/src/App/styles.ts b/packages/__docs__/src/App/styles.ts
index 1a04a3be9d..eb1eb09191 100644
--- a/packages/__docs__/src/App/styles.ts
+++ b/packages/__docs__/src/App/styles.ts
@@ -76,6 +76,21 @@ const generateStyle = (componentTheme: AppTheme): AppStyle => {
       borderInlineEndWidth: componentTheme.navBorderWidth,
       borderInlineEndStyle: 'solid'
     },
+    skipToMainButton: {
+      label: 'skipToMainButton',
+      position: 'absolute',
+      left: '-9999px',
+      zIndex: 999,
+      marginTop: '6px',
+      opacity: 0,
+      height: '60px',
+      fontSize: '150%',
+      '&:focus': {
+        left: '11.5rem',
+        transform: 'translateX(-50%)',
+        opacity: 1
+      }
+    },
     globalStyles: {
       html: {
         height: '100%',
diff --git a/packages/__docs__/src/Hero/index.tsx b/packages/__docs__/src/Hero/index.tsx
index 137333e060..dfe6c1314f 100644
--- a/packages/__docs__/src/Hero/index.tsx
+++ b/packages/__docs__/src/Hero/index.tsx
@@ -52,6 +52,7 @@ import { Heading } from '../Heading'
 
 import type { HeroProps } from './props'
 import { propTypes, allowedProps } from './props'
+import React from 'react'
 
 @withStyle(generateStyle, generateComponentTheme)
 class Hero extends Component<HeroProps> {
@@ -61,6 +62,8 @@ class Hero extends Component<HeroProps> {
     docs: null
   }
 
+  _mainContent?: HTMLElement
+
   componentDidMount() {
     this.props.makeStyles?.()
   }
@@ -69,6 +72,16 @@ class Hero extends Component<HeroProps> {
     this.props.makeStyles?.()
   }
 
+  mainContentRef = (el: Element | null) => {
+    this._mainContent = el as HTMLElement
+  }
+
+  focusMainContent = () => {
+    if (this._mainContent) {
+      this._mainContent.focus()
+    }
+  }
+
   render() {
     const { version, layout, styles } = this.props
 
@@ -191,7 +204,12 @@ class Hero extends Component<HeroProps> {
     const checkmark = <IconCheckMarkSolid inline={false} color="success" />
 
     const heroBodyContent = (
-      <View as="div">
+      <View
+        as="div"
+        elementRef={this.mainContentRef}
+        tabIndex={0}
+        aria-label="main content"
+      >
         <Heading as="h3" level="h2" margin="none none medium">
           Components everyone can count on
         </Heading>
diff --git a/packages/__docs__/src/Nav/index.tsx b/packages/__docs__/src/Nav/index.tsx
index 6dbd6e5ce2..a801b1b243 100644
--- a/packages/__docs__/src/Nav/index.tsx
+++ b/packages/__docs__/src/Nav/index.tsx
@@ -22,7 +22,7 @@
  * SOFTWARE.
  */
 
-import React, { Component } from 'react'
+import React, { Component, createRef } from 'react'
 
 import { IconSearchLine } from '@instructure/ui-icons'
 import { Link } from '@instructure/ui-link'
@@ -38,6 +38,7 @@ import type { NavProps, NavState } from './props'
 class Nav extends Component<NavProps, NavState> {
   _themeId: string
   searchTimeout: ReturnType<typeof setTimeout> | null
+  _textInput?: HTMLElement
   constructor(props: NavProps) {
     super(props)
 
@@ -198,6 +199,22 @@ class Nav extends Component<NavProps, NavState> {
     })
   }
 
+  textInputRef = (el: Element | null) => {
+    this._textInput = el as HTMLElement
+  }
+
+  focusTextInput = () => {
+    if (this._textInput) {
+      this._textInput.focus()
+    }
+  }
+
+  removeFocus = (event) => {
+    if (event.target && event.target.blur) {
+      event.target.blur()
+    }
+  }
+
   renderDocLink(docId: string) {
     const { docs, selected } = this.props
     const docSelected = docId === selected
@@ -223,7 +240,12 @@ class Nav extends Component<NavProps, NavState> {
             background="brand"
           />
         )}
-        <Link display="block" href={`#${docId}`} isWithinText={false}>
+        <Link
+          onClick={this.removeFocus}
+          display="block"
+          href={`#${docId}`}
+          isWithinText={false}
+        >
           {docs[docId].title}
         </Link>
       </View>
@@ -385,7 +407,12 @@ class Nav extends Component<NavProps, NavState> {
             borderWidth={isSelected ? 'none none none large' : 'none'}
             borderColor="brand"
           >
-            <Link display="block" isWithinText={false} href={`#${themeKey}`}>
+            <Link
+              display="block"
+              onClick={this.removeFocus}
+              isWithinText={false}
+              href={`#${themeKey}`}
+            >
               {themeKey}
             </Link>
           </View>
@@ -408,7 +435,14 @@ class Nav extends Component<NavProps, NavState> {
   render() {
     const sections = this.renderSections()
     const themes = this.renderThemes()
-    const icons = <NavToggle key={'icons'} summary={'Icons'} href="#icons" />
+    const icons = (
+      <NavToggle
+        key={'icons'}
+        summary={'Icons'}
+        href="#icons"
+        shouldBlur={true}
+      />
+    )
     const matches = [...sections, ...themes, icons]
     const hasMatches = matches.length > 0
     const errorMessage = [
@@ -432,6 +466,7 @@ class Nav extends Component<NavProps, NavState> {
                 : errorMessage
             }
             shouldNotWrap
+            elementRef={this.textInputRef}
           />
         </View>
         <View margin="medium none none" display="block">
diff --git a/packages/__docs__/src/NavToggle/index.tsx b/packages/__docs__/src/NavToggle/index.tsx
index 431d0aff7e..578c0e0dec 100644
--- a/packages/__docs__/src/NavToggle/index.tsx
+++ b/packages/__docs__/src/NavToggle/index.tsx
@@ -36,7 +36,8 @@ class NavToggle extends Component<NavToggleProps> {
   static allowedProps = allowedProps
   static defaultProps = {
     variant: 'section',
-    children: null
+    children: null,
+    shouldBlur: false
   }
   private _toggle: ToggleDetails | null = null
 
@@ -44,8 +45,15 @@ class NavToggle extends Component<NavToggleProps> {
     this._toggle?.focus()
   }
 
+  blurNavToggle = () => {
+    const { shouldBlur } = this.props
+    if (shouldBlur && document.activeElement instanceof HTMLElement) {
+      document.activeElement.blur()
+    }
+  }
+
   render() {
-    const { summary, variant, ...props } = this.props
+    const { summary, variant, shouldBlur, ...props } = this.props
 
     const isSection = variant === 'section'
 
@@ -67,6 +75,8 @@ class NavToggle extends Component<NavToggleProps> {
         display="block"
         padding="x-small none"
         margin={isSection ? 'none' : 'none none none x-small'}
+        onClick={this.blurNavToggle}
+        as={'div'}
       >
         <InstUISettingsProvider>
           <ToggleDetails
diff --git a/packages/__docs__/src/NavToggle/props.ts b/packages/__docs__/src/NavToggle/props.ts
index da798ec7c3..8413533c23 100644
--- a/packages/__docs__/src/NavToggle/props.ts
+++ b/packages/__docs__/src/NavToggle/props.ts
@@ -35,6 +35,7 @@ type NavToggleOwnProps = {
   summary: string
   variant?: 'section' | 'category'
   children?: React.ReactNode
+  shouldBlur?: boolean
 }
 type PropKeys = keyof NavToggleOwnProps
 
@@ -42,15 +43,21 @@ type AllowedPropKeys = Readonly<Array<PropKeys>>
 
 type NavToggleProps = PickPropsWithExceptions<
   ToggleDetailsProps,
-  'summary' | 'fluidWidth' | keyof NavToggleOwnProps
+  'summary' | 'shouldBlur' | 'fluidWidth' | keyof NavToggleOwnProps
 > &
   NavToggleOwnProps
 
 const propTypes: PropValidators<PropKeys> = {
   summary: PropTypes.string.isRequired,
   variant: PropTypes.oneOf(['section', 'category']),
-  children: PropTypes.node
+  children: PropTypes.node,
+  shouldBlur: PropTypes.bool
 }
-const allowedProps: AllowedPropKeys = ['children', 'summary', 'variant']
+const allowedProps: AllowedPropKeys = [
+  'children',
+  'summary',
+  'variant',
+  'shouldBlur'
+]
 export type { NavToggleProps }
 export { allowedProps, propTypes }