Keyboard Controls documentation

microbit-matt-hillsdon · microbit-matt-hillsdon · commit 9799b55d32aa · 2025-05-08T15:01:08.000+01:00
This uses the sidebar but not the docs system which allows us to pull live shortcut bindings. Particularly useful if we allow custom shortcut bindings going forward. - Moves the tab order of the sidebar docs forward and adds a focus ring. - Handle shortcuts triggered when the sim has focus. - Maximise the mini sim for region nav as it's too small for accessible use. - Added support for escape to close keyboard controls - note this doesn't work for reference docs due to the iframe. Closes #10556
diff --git a/localtypings/pxteditor.d.ts b/localtypings/pxteditor.d.ts
@@ -901,6 +901,8 @@ declare namespace pxt.editor {
 
     export type Activity = "tutorial" | "recipe" | "example";
 
+    export type BuiltInHelp = "keyboardControls";
+
     export interface IProjectView {
         state: IAppState;
         setState(st: IAppState): void;
@@ -958,6 +960,7 @@ declare namespace pxt.editor {
         setSideFile(fn: IFile, line?: number): void;
         navigateToError(diag: pxtc.KsDiagnostic): void;
         setSideDoc(path: string, blocksEditor?: boolean): void;
+        toggleBuiltInSideDoc(help: BuiltInHelp, focusIfOpen: boolean): void;
         setSideMarkdown(md: string): void;
         setSideDocCollapsed(shouldCollapse?: boolean): void;
         removeFile(fn: IFile, skipConfirm?: boolean): void;
diff --git a/pxtsim/accessibility.ts b/pxtsim/accessibility.ts
@@ -13,6 +13,9 @@ namespace pxsim.accessibility {
         if (e.key === "Escape") {
             e.preventDefault();
             return "escape"
+        } else if (e.key === "/" && meta) {
+            e.preventDefault();
+            return "togglekeyboardcontrolshelp";
         } else if (e.key === "u" && meta) {
             e.preventDefault();
             return "navigateregions"
diff --git a/pxtsim/embed.ts b/pxtsim/embed.ts
@@ -75,7 +75,7 @@ namespace pxsim {
         url: string;
     }
 
-    export type SimulatorAction = "escape" | "navigateregions";
+    export type SimulatorAction = "escape" | "navigateregions" | "togglekeyboardcontrolshelp";
 
     export interface SimulatorActionMessage extends SimulatorMessage {
         action: SimulatorAction;
diff --git a/theme/pxt.less b/theme/pxt.less
@@ -11,6 +11,7 @@
 @import 'tutorial';
 @import 'tutorial-sidebar';
 @import 'sidedoc';
+@import 'sidedoc-keyboard-nav-help';
 @import 'home';
 @import 'serial';
 @import 'docs';
diff --git a/theme/sidedoc-keyboard-nav-help.less b/theme/sidedoc-keyboard-nav-help.less
@@ -0,0 +1,50 @@
+/* Import all components */
+@import 'themes/default/globals/site.variables';
+@import 'themes/pxt/globals/site.variables';
+
+/* Reference import */
+@import (reference) "semantic.less";
+
+/*******************************
+        Keyboard nav help 
+*******************************/
+
+#keyboardnavhelp {
+    font-family: @docsPageFont !important;
+    color: @docsTextColor;
+    background-color: @docsBackgroundColor;
+
+    height: 100%;
+    padding: 1rem;
+    overflow: auto;
+    .key {
+        display: inline-flex;
+        justify-content: center;
+        padding: 0.2rem;
+        border: 1px solid var(--pxt-neutral-foreground1);
+        border-radius: 5px;
+        min-width: 1.8em;
+    }
+    .shortcut {
+        gap: 0.5rem;
+    }
+    .hint {
+        font-size: 85%;
+        line-height: 1;
+    }
+    table {
+        width: 100%;
+        table-layout: fixed;
+        text-align: left;
+    }
+    th, td {
+        vertical-align: top;
+        padding: 0.4rem 0.2rem
+    }
+    tr {
+        margin-bottom: 0.3rem;
+    }
+    h3 {
+        margin-top: 2rem;
+    }
+}
diff --git a/theme/sidedoc.less b/theme/sidedoc.less
@@ -63,6 +63,10 @@ code.hljs {
     border-top-left-radius: 5px;
     border-bottom-left-radius: 5px;
     z-index: @sidedocZIndex;
+
+    &:has(aside:focus-visible) {
+        outline: @editorFocusBorderSize solid  var(--pxt-focus-border);
+    }
 }
 
 .sideDocs #sidedocsframe {
diff --git a/webapp/src/app.tsx b/webapp/src/app.tsx
@@ -1437,6 +1437,12 @@ export class ProjectView
         }
     }
 
+    toggleBuiltInSideDoc(help: pxt.editor.BuiltInHelp, focusIfVisible: boolean) {
+        let sd = this.refs["sidedoc"] as container.SideDocs;
+        if (!sd) return;
+        sd.toggleBuiltInHelp(help, focusIfVisible);
+    }
+
     setTutorialInstructionsExpanded(value: boolean): void {
         const tutorialOptions = this.state.tutorialOptions;
         tutorialOptions.tutorialStepExpanded = value;
@@ -1797,6 +1803,13 @@ export class ProjectView
                 this.shouldTryDecompile = true;
             }
 
+            // Onboard accessible blocks if accessible blocks has just been enabled
+            const onboardAccessibleBlocks = pxt.storage.getLocal("onboardAccessibleBlocks") === "1"
+            const sideDocsLoadUrl = onboardAccessibleBlocks ? `${container.builtInPrefix}keyboardControls` : ""
+            if (onboardAccessibleBlocks) {
+                pxt.storage.setLocal("onboardAccessibleBlocks", "0")
+            }
+
             this.setState({
                 home: false,
                 showFiles: h.githubId ? true : false,
@@ -1805,7 +1818,7 @@ export class ProjectView
                 header: h,
                 projectName: h.name,
                 currFile: file,
-                sideDocsLoadUrl: '',
+                sideDocsLoadUrl: sideDocsLoadUrl,
                 debugging: false,
                 isMultiplayerGame: false
             });
@@ -5174,6 +5187,10 @@ export class ProjectView
     }
 
     async toggleAccessibleBlocks() {
+        const nextEnabled = !this.getData<boolean>(auth.ACCESSIBLE_BLOCKS);
+        if (nextEnabled) {
+            pxt.storage.setLocal("onboardAccessibleBlocks", "1")
+        }
         await core.toggleAccessibleBlocks()
         this.reloadEditor();
     }
@@ -5501,8 +5518,8 @@ export class ProjectView
                         <projects.Projects parent={this} ref={this.handleHomeRef} />
                     </div>
                 </div> : undefined}
-                {showEditorToolbar && <editortoolbar.EditorToolbar ref="editortools" parent={this} />}
                 {sideDocs ? <container.SideDocs ref="sidedoc" parent={this} sideDocsCollapsed={this.state.sideDocsCollapsed} docsUrl={this.state.sideDocsLoadUrl} /> : undefined}
+                {showEditorToolbar && <editortoolbar.EditorToolbar ref="editortools" parent={this} />}
                 {sandbox ? undefined : <scriptsearch.ScriptSearch parent={this} ref={this.handleScriptSearchRef} />}
                 {sandbox ? undefined : <extensions.Extensions parent={this} ref={this.handleExtensionRef} />}
                 {inHome ? <projects.ImportDialog parent={this} ref={this.handleImportDialogRef} /> : undefined}
diff --git a/webapp/src/blocks.tsx b/webapp/src/blocks.tsx
@@ -569,10 +569,25 @@ export class Editor extends toolboxeditor.ToolboxEditor {
             focusRingDiv.className = "blocklyWorkspaceFocusRingLayer";
             this.editor.getSvgGroup().addEventListener("focus", () => {
                 focusRingDiv.dataset.focused = "true";
-            })
+            });
             this.editor.getSvgGroup().addEventListener("blur", () => {
                 delete focusRingDiv.dataset.focused;
-            })
+            });
+
+            const listShortcuts = Blockly.ShortcutRegistry.registry.getRegistry()["list_shortcuts"];
+            Blockly.ShortcutRegistry.registry.unregister(listShortcuts.name);
+            Blockly.ShortcutRegistry.registry.register({
+                ...listShortcuts,
+                keyCodes: [
+                    Blockly.ShortcutRegistry.registry.createSerializedKey(Blockly.utils.KeyCodes.SLASH, [
+                        Blockly.utils.KeyCodes.META,
+                    ]),
+                    Blockly.ShortcutRegistry.registry.createSerializedKey(Blockly.utils.KeyCodes.SLASH, [
+                        Blockly.utils.KeyCodes.CTRL,
+                    ]),
+                ]
+            });
+
 
             const cleanUpWorkspace = Blockly.ShortcutRegistry.registry.getRegistry()["clean_up_workspace"];
             Blockly.ShortcutRegistry.registry.unregister(cleanUpWorkspace.name);
@@ -592,6 +607,10 @@ export class Editor extends toolboxeditor.ToolboxEditor {
                         this.parent.setSimulatorFullScreen(false);
                         return;
                     }
+                    case "togglekeyboardcontrolshelp": {
+                        this.parent.toggleBuiltInSideDoc("keyboardControls", false);
+                        return
+                    }
                     case "navigateregions" : {
                         this.parent.showNavigateRegions();
                         return
diff --git a/webapp/src/components/KeyboardControlsHelp.tsx b/webapp/src/components/KeyboardControlsHelp.tsx
@@ -0,0 +1,176 @@
+import * as React from "react";
+import { getActionShortcut, SHORTCUT_NAMES } from "../shortcut_formatting";
+
+const KeyboardControlsHelp = () => {
+    const ref = React.useRef<HTMLElement>(null);
+    React.useEffect(() => {
+        ref.current?.focus()
+    }, []);
+    const ctrl = lf("Ctrl");
+    const cmd = pxt.BrowserUtils.isMac() ? "⌘" : ctrl;
+    const optionOrCtrl = pxt.BrowserUtils.isMac() ? "⌥" : ctrl;
+    const contextMenuRow = <Row name={lf("Open context menu")} shortcuts={[SHORTCUT_NAMES.MENU]} />
+    const cleanUpRow = <Row name={lf("Workspace: Format code")} shortcuts={[SHORTCUT_NAMES.CLEAN_UP]} />
+    const orAsJoiner = lf("or")
+    const enterOrSpace = { shortcuts: [[lf("Enter")], [lf("Space")]], joiner: orAsJoiner}
+    const editOrConfirmRow = <Row name={lf("Edit or confirm")} {...enterOrSpace} />
+    return (
+        <aside id="keyboardnavhelp" aria-label={lf("Keyboard Controls")} ref={ref} tabIndex={0}>
+            <h2>{lf("Keyboard Controls")}</h2>
+            <table>
+                <tbody>
+                    <Row name={lf("Show/hide shortcut help")} shortcuts={[SHORTCUT_NAMES.LIST_SHORTCUTS]} />
+                    <Row name={lf("Jump to region")} shortcuts={[[cmd, "U"]]} />
+                    <Row name={lf("Block and toolbox navigation")} shortcuts={[SHORTCUT_NAMES.UP, SHORTCUT_NAMES.DOWN, SHORTCUT_NAMES.LEFT, SHORTCUT_NAMES.RIGHT]} />
+                    <Row name={lf("Toolbox or insert")} shortcuts={[SHORTCUT_NAMES.TOOLBOX, SHORTCUT_NAMES.INSERT]} joiner={orAsJoiner} />
+                    {editOrConfirmRow}
+                    <Row name={lf("Move mode")} shortcuts={[["M"]]} >
+                        <br /><span className="hint">{lf("Move with arrow keys")}</span>
+                        <br /><span className="hint">{lf("Hold {0} for free movement", optionOrCtrl)}</span>
+                    </Row>
+                    <Row name={lf("Copy / paste")} shortcuts={[SHORTCUT_NAMES.COPY, SHORTCUT_NAMES.PASTE]} joiner="/" />
+                    {cleanUpRow}
+                    {contextMenuRow}
+                </tbody>
+            </table>
+            <h3>{lf("Editor Overview")}</h3>
+            <table>
+                <tbody>
+                    <Row name={lf("Move between menus, simulator and the workspace")} shortcuts={[[lf("Tab")], [lf("Shift"), lf("Tab")]]} joiner="row"/>
+                    <Row name={lf("Jump to region")} shortcuts={[[cmd, "U"]]} />
+                    <Row name={lf("Exit")} shortcuts={[SHORTCUT_NAMES.EXIT]} />
+                    <Row name={lf("Toolbox")} shortcuts={[SHORTCUT_NAMES.TOOLBOX]} />
+                    <Row name={lf("Toolbox: Move in and out of categories")} shortcuts={[SHORTCUT_NAMES.LEFT, SHORTCUT_NAMES.RIGHT]} />
+                    <Row name={lf("Toolbox: Navigate categories or blocks")} shortcuts={[SHORTCUT_NAMES.UP, SHORTCUT_NAMES.DOWN]} />
+                    <Row name={lf("Toolbox: Insert block")} {...enterOrSpace} />
+                    <Row name={lf("Workspace: Select workspace")} shortcuts={[["W"]]} />
+                    {cleanUpRow}
+                </tbody>
+            </table>
+            <h3>{lf("Edit Blocks")}</h3>
+            <table>
+                <tbody>
+                    <Row name={lf("Move in and out of a block")} shortcuts={[SHORTCUT_NAMES.LEFT, SHORTCUT_NAMES.RIGHT]} />
+                    {editOrConfirmRow}
+                    <Row name={lf("Cancel or exit")} shortcuts={[SHORTCUT_NAMES.EXIT]} />
+                    <Row name={lf("Insert block at current position")} shortcuts={[SHORTCUT_NAMES.INSERT]} />
+                    <Row name={lf("Copy")} shortcuts={[SHORTCUT_NAMES.COPY]} />
+                    <Row name={lf("Paste")} shortcuts={[SHORTCUT_NAMES.PASTE]} />
+                    <Row name={lf("Cut")} shortcuts={[SHORTCUT_NAMES.CUT]} />
+                    <Row name={lf("Delete")} shortcuts={[SHORTCUT_NAMES.DELETE, [lf("Backspace")]]} joiner={orAsJoiner} />
+                    <Row name={lf("Undo")} shortcuts={[SHORTCUT_NAMES.UNDO]} />
+                    <Row name={lf("Redo")} shortcuts={[SHORTCUT_NAMES.REDO]} />
+                    {contextMenuRow}
+                </tbody>
+            </table>
+            <h3>{lf("Moving Blocks")}</h3>
+            <table>
+                <tbody>
+                    <Row name={lf("Move mode")} shortcuts={[["M"]]} />
+                    <Row name={lf("Move mode: Move to new position")} shortcuts={[SHORTCUT_NAMES.UP, SHORTCUT_NAMES.DOWN, SHORTCUT_NAMES.LEFT, SHORTCUT_NAMES.RIGHT]} />
+                    <Row name={lf("Move mode: Free movement")}>
+                        {lf("Hold {0} and press arrow keys", optionOrCtrl)}
+                    </Row>
+                    <Row name={lf("Move mode: Confirm")} {...enterOrSpace} />
+                    <Row name={lf("Move mode: Cancel")} shortcuts={[SHORTCUT_NAMES.EXIT]} />
+                    <Row name={lf("Disconnect blocks")} shortcuts={[SHORTCUT_NAMES.DISCONNECT]} />
+                </tbody>
+            </table>
+        </aside>
+    );
+}
+
+const Shortcut = ({ keys }: { keys: string[] }) => {
+    const joiner = pxt.BrowserUtils.isMac() ? " " : " + "
+    return (
+        <span className="shortcut">
+            {keys.reduce((acc, key) => {
+                return acc.length === 0
+                    ? [...acc,  <Key key={key} value={key} />]
+                    : [...acc, joiner, <Key key={key} value={key} />]
+            }, [])}
+        </span>
+    );
+}
+
+interface RowProps {
+    name: string;
+    shortcuts?: Array<string | string[]>;
+    joiner?: string;
+    children?: React.ReactNode;
+}
+
+const Row = ({ name, shortcuts = [], joiner, children}: RowProps) => {
+    const shortcutElements = shortcuts.map((s, idx) => {
+        if (typeof s === "string") {
+            // Pull keys from shortcut registry.
+            return <Shortcut key={idx} keys={getActionShortcut(s)} />
+        } else {
+            // Display keys as specified.
+            return <Shortcut key={idx} keys={s} />
+        }
+    })
+    return joiner === "row" ? (
+        <>
+            <tr>
+                <td width="50%" rowSpan={shortcuts.length}>{name}</td>
+                <td width="50%">
+                    {shortcutElements[0]}
+                </td>
+            </tr>
+            {shortcutElements.map((el, idx) => idx === 0
+                ? undefined
+                : (<tr key={idx}>
+                        <td width="50%">
+                            {el}
+                        </td>
+                    </tr>))}
+        </>
+    ) : (
+        <tr>
+            <td width="50%">{name}</td>
+            <td width="50%">
+                {shortcutElements.reduce((acc, shortcut) => {
+                    return acc.length === 0
+                        ? [...acc,  shortcut]
+                        : [...acc, joiner ? ` ${joiner} ` : " ", shortcut]
+                }, [])}
+                {children}
+                <br />
+            </td>
+        </tr>
+    )
+}
+
+const Key = ({ value }: { value: string }) => {
+    let aria;
+    switch (value) {
+        case "↑": {
+            aria = lf("Up Arrow");
+            break;
+        }
+        case "↓": {
+            aria = lf("Down Arrow");
+            break;
+        }
+        case "←": {
+            aria = lf("Left Arrow");
+            break;
+        }
+        case "→": {
+            aria = lf("Right Arrow");
+            break;
+        }
+        case "⌘": {
+            aria = lf("Command");
+            break;
+        }
+        case "⌥": {
+            aria = lf("Option");
+            break;
+        }
+    }
+    return <span className="key" aria-label={aria}>{lf("{0}", value)}</span>
+}
+
+export default KeyboardControlsHelp;
diff --git a/webapp/src/container.tsx b/webapp/src/container.tsx
diff --git a/webapp/src/keynames.ts b/webapp/src/keynames.ts
diff --git a/webapp/src/shortcut_formatting.ts b/webapp/src/shortcut_formatting.ts

Original file line number	Diff line number	Diff line change
`@@ -75,7 +75,7 @@ namespace pxsim {`
`75`	`75`	`url: string;`
`76`	`76`	`}`
`77`	`77`
`78`		`- export type SimulatorAction = "escape" \| "navigateregions";`
	`78`	`+ export type SimulatorAction = "escape" \| "navigateregions" \| "togglekeyboardcontrolshelp";`
`79`	`79`
`80`	`80`	`export interface SimulatorActionMessage extends SimulatorMessage {`
`81`	`81`	`action: SimulatorAction;`