Tab navigation improvement for the docs sidebar

Author: glastonbridge

theme/docs.less

@@ -29,6 +29,7 @@
 
 @docsCardBorderColor: #e9eef2;
 @docsCardHoverBorderColor: #1dacf4;
+@docsCardFocusBorderColor: #0078D4; // --pxt-focus-border not available in iframed documentation
 
 #docs .footer,
 #docs .topbar,
@@ -219,6 +220,7 @@
     #sidedocs-back-button {
         margin-top: 1.25rem;
         margin-left: 1.25rem;
+        margin-right: 5rem; // Safety margin for the "open in new tab" button
         cursor: pointer;
         user-select: none;
         color: var(--pxt-page-foreground);
@@ -227,6 +229,11 @@
         &:hover {
             text-decoration: none;
         }
+
+        &:focus-visible {
+            outline: 3px solid @docsCardFocusBorderColor;
+            outline-offset: 3px;
+        }
     }
 
     #sidedocs-back-button.disabled {
@@ -483,6 +490,10 @@
 
 .sideDocs #sidedocsbar a {
     color: @docsLinkColor;
+    &:focus-visible {
+        outline: 3px solid var(--pxt-focus-border);
+        outline-offset: 3px;
+    }
 }
 
 .replaceDocsAvatar() when not (@docsAvatarImage = none) {

webapp/src/container.tsx

@@ -608,12 +608,14 @@ export interface SideDocsState {
 interface BuiltInHelpDetails {
     component: () => JSX.Element;
     popOutHref: string;
+    singleTabStop: boolean; // if the whole doc is only one tab stop, the "open in new tab" button placement becomes unintuitive.
 }
 
 const builtIns: Record<pxt.editor.BuiltInHelp, BuiltInHelpDetails> = {
     "keyboardControls": {
         component: KeyboardControlsHelp,
-        popOutHref: "https://makecode.com/accessibility"
+        popOutHref: "https://makecode.com/accessibility",
+        singleTabStop: true
     }
 }
 
@@ -778,20 +780,27 @@ export class SideDocs extends data.Component<SideDocsProps, SideDocsState> {
             tabIndex: 0,
         };
 
+        const openInNewTab = !lockedEditor && <div className="ui app hide" id="sidedocsbar">
+                    <a className="ui icon link" aria-label={lf("Open documentation in new tab")} {...openInNewTabLinkProps}>
+                        <sui.Icon icon="external" />
+                    </a>
+                </div>;
+
+        const content =  <div id="sidedocsframe-wrapper">
+                    {this.renderContent(url, builtIn, lockedEditor)}
+                </div>;
+
+        const flipNewTabLinkOrder = builtIn?.singleTabStop;
+
+        const contentParts = flipNewTabLinkOrder ? [content, openInNewTab] : [openInNewTab, content];
+
         /* eslint-disable @microsoft/sdl/react-iframe-missing-sandbox */
         return <div>
             <button id="sidedocstoggle" role="button" aria-label={sideDocsCollapsed ? lf("Expand the side documentation") : lf("Collapse the side documentation")} className="ui icon button large" onClick={this.toggleVisibility}>
                 <sui.Icon icon={`icon inverted chevron ${showLeftChevron ? 'left' : 'right'}`} />
             </button>
             <div id="sidedocs" onKeyDown={this.handleKeyDown}>
-                {!lockedEditor && <div className="ui app hide" id="sidedocsbar">
-                    <a className="ui icon link" aria-label={lf("Open documentation in new tab")} {...openInNewTabLinkProps}>
-                        <sui.Icon icon="external" />
-                    </a>
-                </div>}
-                <div id="sidedocsframe-wrapper">
-                    {this.renderContent(url, builtIn, lockedEditor)}
-                </div>
+                {contentParts}
             </div>
         </div>
         /* eslint-enable @microsoft/sdl/react-iframe-missing-sandbox */