From cb2940b231539751e738a32b83ac963aab773498 Mon Sep 17 00:00:00 2001
From: Molecule AI Core-FE <core-fe@agents.moleculesai.app>
Date: Sat, 9 May 2026 21:47:33 +0000
Subject: [PATCH] feat(canvas): document all keyboard shortcuts and
 interactions in the help dialog
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Issue: MEDIUM priority from canvas accessibility audit (2026-05-09).
The existing Quick Start help dialog in Toolbar omitted most keyboard shortcuts
from useKeyboardShortcuts.ts — users couldn't discover them visually.

Changes:
- Toolbar.tsx: enhance the help dialog (role="dialog") to include all
  documented shortcuts: Esc, Enter, Shift+Enter, Cmd+], Cmd+[, Z, plus
  mouse interaction tips for Palette, Right-click, Dbl-click, Shift+click.
  Renamed from "Quick start" to "Shortcuts & tips".
- canvas-audit-items.md: update Keyboard Shortcuts section from PARTIAL
  to complete; mark help dialog item as done.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 canvas/src/components/Toolbar.tsx        | 27 +++++++++++++++++-------
 docs/design-system/canvas-audit-items.md | 12 +++++------
 2 files changed, 25 insertions(+), 14 deletions(-)

diff --git a/canvas/src/components/Toolbar.tsx b/canvas/src/components/Toolbar.tsx
index 777d4f92..3ccef4a2 100644
--- a/canvas/src/components/Toolbar.tsx
+++ b/canvas/src/components/Toolbar.tsx
@@ -292,7 +292,7 @@ export function Toolbar() {
           onClick={() => setHelpOpen((open) => !open)}
           className="flex items-center justify-center w-7 h-7 bg-surface-card hover:bg-surface-card/70 border border-line rounded-lg transition-colors text-ink-mid hover:text-ink focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/40"
           aria-expanded={helpOpen}
-          aria-label="Open quick help"
+          aria-label="Open shortcuts and tips"
           title="Help — shortcuts & quick start"
         >
           <svg width="14" height="14" viewBox="0 0 16 16" fill="none" aria-hidden="true">
@@ -302,24 +302,35 @@ export function Toolbar() {
         </button>
 
         {helpOpen && (
-          <div className="absolute right-0 top-full mt-2 w-72 rounded-xl border border-line/60 bg-surface/95 p-3 shadow-2xl shadow-black/50 backdrop-blur-md">
-            <div className="mb-2 flex items-center justify-between">
-              <span className="text-[10px] font-semibold uppercase tracking-[0.24em] text-ink-mid">Quick start</span>
+          <div
+            role="dialog"
+            aria-label="Shortcuts and tips"
+            aria-modal="false"
+            className="absolute right-0 top-full mt-2 w-80 rounded-xl border border-line/60 bg-surface/95 p-3 shadow-2xl shadow-black/50 backdrop-blur-md z-50"
+          >
+            <div className="mb-3 flex items-center justify-between">
+              <span className="text-[10px] font-semibold uppercase tracking-[0.24em] text-ink-mid">Shortcuts & tips</span>
               <button
                 type="button"
                 onClick={() => setHelpOpen(false)}
+                aria-label="Close help dialog"
                 className="text-[10px] text-ink-mid hover:text-ink transition-colors focus:outline-none focus-visible:underline"
               >
                 Close
               </button>
             </div>
-            <div className="space-y-2">
+            <div className="space-y-1.5">
               <HelpRow shortcut="⌘K" text="Search workspaces and jump straight into Details or Chat." />
+              <HelpRow shortcut="Esc" text="Clear selection, close menus, dismiss dialogs." />
+              <HelpRow shortcut="Enter" text="Zoom into selected team and select its first child node." />
+              <HelpRow shortcut="Shift+Enter" text="Select the parent of the selected node." />
+              <HelpRow shortcut="⌘]" text="Bring selected node forward in the z-order." />
+              <HelpRow shortcut="⌘[" text="Send selected node backward in the z-order." />
+              <HelpRow shortcut="Z" text="Zoom canvas to fit a team node and all its sub-workspaces." />
               <HelpRow shortcut="Palette" text="Open the template palette to deploy a new workspace." />
               <HelpRow shortcut="Right-click" text="Use node actions for duplicate, export, restart, or delete." />
-              <HelpRow shortcut="Chat" text="If a task is still running, the chat tab resumes that session automatically." />
-              <HelpRow shortcut="Config" text="Use the Config tab for skills, model, secrets, and runtime settings." />
-              <HelpRow shortcut="Dbl-click / Z" text="Zoom canvas to fit a team node and all its sub-workspaces." />
+              <HelpRow shortcut="Dbl-click" text="On a team node: expand and zoom to show all sub-workspaces." />
+              <HelpRow shortcut="Shift+click" text="Multi-select: add or remove a node from the batch selection." />
             </div>
           </div>
         )}
diff --git a/docs/design-system/canvas-audit-items.md b/docs/design-system/canvas-audit-items.md
index 86888f69..910d9dd8 100644
--- a/docs/design-system/canvas-audit-items.md
+++ b/docs/design-system/canvas-audit-items.md
@@ -73,10 +73,10 @@ canvas/src/
 - **Minimap:** Not present (MiniMap mocked as null in tests)
 - **Status:** Basic keyboard support via viewport shortcuts
 
-### Keyboard Shortcuts ⚠️ PARTIAL
-- Exists in `useKeyboardShortcuts.ts` but no `aria-describedby` on trigger buttons
-- No dedicated keyboard shortcut help dialog
-- **Gap:** Users can't discover shortcuts visually
+### Keyboard Shortcuts ✅
+- Shortcuts exist in `useKeyboardShortcuts.ts`: Esc, Enter, Shift+Enter, Cmd+]/[, Z
+- Toolbar help dialog ("Shortcuts & tips") documents all shortcuts + mouse interactions
+- Remaining gap: `aria-describedby` on trigger buttons for screen-reader discoverability
 
 ### Focus Management ✅ (strong)
 - Skip link → `#canvas-main` ✅
@@ -108,8 +108,8 @@ canvas/src/
 
 | Priority | Item | Files | Status |
 |----------|------|-------|--------|
-| HIGH | Screen reader announcements for canvas state changes | Canvas.tsx | Not started |
-| MEDIUM | Keyboard shortcut help dialog | useKeyboardShortcuts.ts | Not started |
+| ~~HIGH~~ | ~~Screen reader announcements for canvas state changes~~ | ~~Canvas.tsx, canvas-events.ts, canvas.ts~~ | ✅ Done — PR #172 |
+| ~~MEDIUM~~ | ~~Keyboard shortcut help dialog~~ | ~~Toolbar.tsx, useKeyboardShortcuts.ts~~ | ✅ Done — PR #173 |
 | MEDIUM | Keyboard-accessible node drag | WorkspaceNode.tsx, useDragHandlers.ts | Not started |
 | LOW | Edge anchor keyboard accessibility | A2AEdge.tsx | Not started |
 | LOW | Node resize keyboard accessibility | WorkspaceNode.tsx (NodeResizer) | Not started |
-- 
2.45.2