Return focus to variant after cross variant navigation

Closes #483

Author: lukekarrys

cli/lib/build.js

@@ -14,6 +14,7 @@ const updateNav = async (updates, {nav, path}) => {
     shortName: release.id,
     url: release.url,
     default: release.default,
+    type: release.type,
     children: release.nav,
   }))
 
@@ -43,7 +44,7 @@ const getCurrentVersions = nav => {
 
   const currentVersions = currentSections
     .map(v => {
-      const version = v.title?.match(/^Version\s(.*?)\s/)[1]
+      const version = v.title?.match(/^Version\s(.*?)$/)[1]
       return version
     })
     .sort(semver.compare)
@@ -95,16 +96,17 @@ const main = async ({loglevel, releases: rawReleases, useCurrent, navPath, conte
 
   const releases = releaseVersions.map(release => {
     const type = release.default
-      ? 'Latest Release'
+      ? 'latest'
       : release.prerelease
-      ? 'Prerelease'
+      ? 'prerelease'
       : semver.gt(release.version, latestRelease.version)
-      ? 'Current Release'
-      : 'Legacy Release'
+      ? 'current'
+      : 'legacy'
 
     return {
       ...release,
-      title: `Version ${release.version} (${type})`,
+      type,
+      title: `Version ${release.version}`,
       url: `/${DOCS_PATH}/${release.id}`,
       urlPrefix: DOCS_PATH,
       urlPrefixes: [DOCS_PATH, `${DOCS_PATH}-documentation`],

content/nav.yml

@@ -283,10 +283,11 @@
   shortName: CLI
   url: /cli
   variants:
-    - title: Version 6.14.18 (Legacy Release)
+    - title: Version 6.14.18
       shortName: v6
       url: /cli/v6
       default: false
+      type: legacy
       children:
         - title: CLI Commands
           shortName: Commands
@@ -525,10 +526,11 @@
             - title: Changelog
               url: /cli/v6/using-npm/changelog
               description: Changelog notes for each version
-    - title: Version 7.24.2 (Legacy Release)
+    - title: Version 7.24.2
       shortName: v7
       url: /cli/v7
       default: false
+      type: legacy
       children:
         - title: CLI Commands
           shortName: Commands
@@ -782,10 +784,11 @@
             - title: Changelog
               url: /cli/v7/using-npm/changelog
               description: Changelog notes for each version
-    - title: Version 8.19.4 (Legacy Release)
+    - title: Version 8.19.4
       shortName: v8
       url: /cli/v8
       default: false
+      type: legacy
       children:
         - title: CLI Commands
           shortName: Commands
@@ -1051,10 +1054,11 @@
             - title: Changelog
               url: /cli/v8/using-npm/changelog
               description: Changelog notes for each version
-    - title: Version 9.9.0 (Legacy Release)
+    - title: Version 9.9.0
       shortName: v9
       url: /cli/v9
       default: false
+      type: legacy
       children:
         - title: CLI Commands
           shortName: Commands
@@ -1320,10 +1324,11 @@
             - title: Changelog
               url: /cli/v9/using-npm/changelog
               description: Changelog notes for each version
-    - title: Version 10.2.1 (Latest Release)
+    - title: Version 10.2.1
       shortName: v10
       url: /cli/v10
       default: true
+      type: latest
       children:
         - title: CLI Commands
           shortName: Commands

src/components/skip-nav.js

@@ -0,0 +1,50 @@
+import React from 'react'
+import {Box} from '@primer/react'
+import styled from 'styled-components'
+import Link from './link'
+import {SCROLL_MARGIN_TOP} from '../constants'
+
+const ID = 'skip-nav'
+
+const SkipLinkBase = props => (
+  <Link
+    {...props}
+    href={`#${ID}`}
+    sx={{
+      p: 3,
+      color: 'fg.onEmphasis',
+      backgroundColor: 'accent.emphasis',
+      fontSize: 1,
+    }}
+  >
+    Skip to content
+  </Link>
+)
+
+// The following rules are to ensure that the element is visually hidden, unless
+// it has focus. This is the recommended way to hide content from:
+// https://webaim.org/techniques/css/invisiblecontent/#techniques
+export const SkipLink = styled(SkipLinkBase)`
+  z-index: 20;
+  width: auto;
+  height: auto;
+  clip: auto;
+  position: absolute;
+  overflow: hidden;
+  left: 10px;
+
+  &:not(:focus) {
+    clip: rect(1px, 1px, 1px, 1px);
+    clip-path: inset(50%);
+    height: 1px;
+    width: 1px;
+    margin: -1px;
+    padding: 0;
+  }
+`
+
+const SkipNavBase = props => <Box id={ID} {...props} />
+
+export const SkipNav = styled(SkipNavBase)`
+  scroll-margin-top: ${SCROLL_MARGIN_TOP}px;
+`

src/components/table-of-contents.js

@@ -2,7 +2,7 @@ import React from 'react'
 import {Heading, Box, Details, useDetails, Button} from '@primer/react'
 import {ChevronDownIcon, ChevronRightIcon} from '@primer/octicons-react'
 import {NavList} from '@primer/react/drafts'
-import {FULL_HEADER_HEIGHT} from '../constants'
+import {SCROLL_MARGIN_TOP} from '../constants'
 import usePage from '../hooks/use-page'
 
 const TableOfContentsItems = ({items, depth}) => (
@@ -54,16 +54,17 @@ export const Desktop = withTableOfContents(({items}) => (
       marginLeft: [null, 7, 8, 9],
       display: ['none', null, 'block'],
       position: 'sticky',
-      top: FULL_HEADER_HEIGHT + 48,
-      maxHeight: `calc(100vh - ${FULL_HEADER_HEIGHT + 48}px)`,
+      top: SCROLL_MARGIN_TOP,
+      maxHeight: `calc(100vh - ${SCROLL_MARGIN_TOP}px)`,
     }}
   >
     <Heading as="h3" sx={{fontSize: 1, display: 'inline-block', fontWeight: 'bold'}} id="toc-heading">
       Table of contents
     </Heading>
     <Box
       sx={{
-        maxHeight: `calc(100% - 21px)`,
+        // extra pixels to account for table of contents title height
+        maxHeight: `calc(100% - 24px)`,
         overflowY: 'scroll',
       }}
     >

src/components/variant-select.js

@@ -1,93 +1,131 @@
 import React from 'react'
 import {ActionList, ActionMenu, Box} from '@primer/react'
-import {navigate} from 'gatsby'
 import * as getNav from '../util/get-nav'
 import usePage from '../hooks/use-page'
+import Link from './link'
 
-const VariantItem = ({match, active}) => {
-  const {variant, page} = match
+const VariantItem = ({title, shortName, url, active}) => (
+  <ActionList.Item
+    as={Link}
+    to={url}
+    id={shortName}
+    active={active}
+    sx={{
+      ':hover': {textDecoration: 'none'},
+    }}
+  >
+    {title}
+  </ActionList.Item>
+)
 
-  const navigateToPage = React.useCallback(() => navigate(`${page.url}?v=true`), [page.url])
+const useVariantFocus = path => {
+  const anchorRef = React.useRef(null)
+  const pathRef = React.useRef(null)
 
-  const handleClick = React.useCallback(
-    event => {
-      event.preventDefault()
-      navigateToPage()
-    },
-    [navigateToPage],
-  )
+  React.useEffect(() => {
+    const previousPath = pathRef.current
+    pathRef.current = path
 
-  const handleKey = React.useCallback(
-    event => {
-      if (event.key === 'Enter') {
-        navigateToPage()
+    if (getNav.didVariantChange(previousPath, path)) {
+      const anchor = anchorRef.current
+      const onBlur = () => {
+        anchor.removeEventListener('blur', onBlur)
+        anchor.focus()
       }
-    },
-    [navigateToPage],
-  )
+      anchor.addEventListener('blur', onBlur)
+      return () => anchor.removeEventListener('blur', onBlur)
+    }
+  }, [path])
 
-  return (
-    <ActionList.Item onKeyDown={handleKey} onClick={handleClick} id={variant.shortName} active={active}>
-      {variant.title}
-    </ActionList.Item>
-  )
+  return anchorRef
 }
 
-const VariantMenu = ({variants, path}) => {
+const VariantMenu = ({title, latest, current, prerelease, legacy, path}) => {
   const [open, setOpen] = React.useState(false)
-
-  const {selected, items} = variants.reduce(
-    (acc, match, key) => {
-      const active = match.page.url === path
-      if (active) {
-        acc.selected = match
-      }
-      acc.items.push({match, key, active})
-      return acc
-    },
-    {selected: variants[0], items: []},
-  )
+  const anchorRef = useVariantFocus(path)
+  const labelId = 'label-versions-list-item'
 
   return (
     <>
-      <Box as="p" sx={{m: 0}} id="label-versions-list-item">
+      <Box as="p" sx={{m: 0}} id={labelId}>
         Select CLI Version:
       </Box>
-      <ActionMenu open={open} onOpenChange={setOpen}>
-        {/* Disabling to remove lint warnings. This property was added as "autofocus"
-        in a previous accessibility audit which did not trigger the lint warning. */
-        /* eslint-disable-next-line jsx-a11y/no-autofocus */}
-        <ActionMenu.Button autoFocus aria-describedby="label-versions-list-item">
-          {selected.variant.title}
-        </ActionMenu.Button>
-        <ActionMenu.Overlay width="medium" onEscape={() => setOpen(false)}>
-          <ActionList id="versions-list-item" aria-labelledby="label-versions-list-item">
-            {items.map(item => (
-              <VariantItem key={item.key} {...item} />
-            ))}
+      <ActionMenu anchorRef={anchorRef} open={open} onOpenChange={setOpen}>
+        <ActionMenu.Button aria-describedby={labelId}>{title}</ActionMenu.Button>
+        <ActionMenu.Overlay width="auto" onEscape={() => setOpen(false)}>
+          <ActionList aria-labelledby={labelId}>
+            <ActionList.Group title="Current">
+              <VariantItem {...latest} />
+              {current && <VariantItem {...current} />}
+              {prerelease && <VariantItem {...prerelease} />}
+            </ActionList.Group>
+            {legacy && (
+              <ActionList.Group title="Legacy">
+                {legacy.map(item => (
+                  <VariantItem key={item.title} {...item} />
+                ))}
+              </ActionList.Group>
+            )}
           </ActionList>
         </ActionMenu.Overlay>
       </ActionMenu>
     </>
   )
 }
 
-const VariantSelect = () => {
-  const {location} = usePage()
-  const root = getNav.getVariantRoot(location.pathname)
-  const path = getNav.getPath(location.pathname)
-  const vp = getNav.getVariantAndPage(root, path)
-  const variants = vp ? getNav.getVariantsForPage(root, vp.page) : []
+const useVariants = () => {
+  const {pathname} = usePage().location
 
-  if (!variants.length) {
-    return null
-  }
+  return React.useMemo(() => {
+    const root = getNav.getVariantRoot(pathname)
+    const path = getNav.getPath(pathname)
+    const vp = getNav.getVariantAndPage(root, path)
+    const variantPages = vp ? getNav.getVariantsForPage(root, vp.page) : []
 
-  return (
+    if (!variantPages.length) {
+      return null
+    }
+
+    const result = {path, latest: null, current: null, prerelease: null, legacy: []}
+
+    for (const {variant, page} of variantPages) {
+      const item = {...variant, url: page.url, active: page.url === path}
+      let typeDesc = ''
+      switch (variant.type) {
+        case 'latest':
+          result.latest = item
+          typeDesc = ' (Latest)'
+          break
+        case 'current':
+          result.current = item
+          typeDesc = ' (Current)'
+          break
+        case 'prerelease':
+          result.prerelease = item
+          typeDesc = ' (Prerelease)'
+          break
+        default:
+          result.legacy.push(item)
+          typeDesc = ' Legacy'
+      }
+      if (item.active) {
+        result.title = `${item.title}${typeDesc}`
+      }
+    }
+
+    result.legacy.sort((a, b) => parseInt(b.shortName.slice(1)) - parseInt(a.shortName.slice(1)))
+
+    return result
+  }, [pathname])
+}
+
+const VariantSelect = () => {
+  const variants = useVariants()
+  return variants ? (
     <Box sx={{mt: 2, mb: 3}}>
-      <VariantMenu variants={variants} path={path} />
+      <VariantMenu {...variants} />
     </Box>
-  )
+  ) : null
 }
 
 export default VariantSelect

src/constants.js

@@ -4,4 +4,4 @@ export const HEADER_BAR = 10
 
 export const FULL_HEADER_HEIGHT = HEADER_HEIGHT + HEADER_BAR
 
-export const SKIP_NAV = {id: 'skip-nav', as: 'main'}
+export const SCROLL_MARGIN_TOP = FULL_HEADER_HEIGHT + 24