added keyboard navigation to wall pan

Signed-off-by: Mark Rai <markraidc@gmail.com>

Author: markrai

CHANGELOG.md

@@ -11,6 +11,7 @@
 ### Improvements
 
 - **Wall coordinates** - Notes can be placed at negative canvas coordinates (matching the server’s ±100000 bound). Drag, resize, marquee select, edge preview, and create-at-pointer all use a shared screen-to-canvas transform so gestures stay correct at any zoom.
+- **Wall keyboard pan** - **Arrow keys** pan the canvas (hold **Shift** for larger steps), complementing scroll-wheel, middle-drag, and Space+drag for users without horizontal scroll or a middle button. Suppressed while editing a note or when focus is in an input/button.
 
 ### Fixed
 

docs/wall-viewport-manual-checklist.md

@@ -19,5 +19,7 @@ Run each scenario in a real browser (Chromium/Firefox) at **zoom ≠ 1** and wit
 | 13 | Edit suppression | Wheel / Space+drag do nothing while editing note text |
 | 14 | Input suppression | Wheel does nothing when focus in textarea/button |
 | 15 | Teardown | Close wall → Space pan not stuck; page scroll normal |
+| 16 | Arrow-key pan | Arrow keys pan the canvas; Shift = larger steps; page behind modal does not scroll |
+| 17 | Arrow suppression | Arrow keys move the caret (no pan) while editing note text or with focus in an input/button |
 
-Navigation reference: wheel = pan, Ctrl/Cmd+wheel = zoom, middle-drag / Space+drag = pan.
+Navigation reference: wheel = pan, Ctrl/Cmd+wheel = zoom, middle-drag / Space+drag / arrow keys = pan.

docs/wall.md

@@ -21,7 +21,7 @@ Sticky-note board for durable projects. Open it from the board topbar (desktop o
 - **Exit multi-select on canvas** - **Click** empty space (no drag).
 - **Move a group** - With multiple notes selected, drag one of them; all selected notes move together. Selection clears when you release the drag.
 - **Delete several at once** - Drag the group over the trash; one confirmation lists how many notes will be deleted.
-- **Pan the canvas** - Scroll wheel, **middle-mouse drag**, or hold **Space** and drag on empty canvas.
+- **Pan the canvas** - Scroll wheel, **middle-mouse drag**, hold **Space** and drag on empty canvas, or use the **arrow keys** (hold **Shift** for larger steps).
 - **Zoom** - **Ctrl**+scroll (Windows/Linux) or **⌘**+scroll (Mac). Pinch-to-zoom on trackpads uses the same modifier.
 - **Fit view** - Click the **⊡** button (top-right, beside close) or press **F** while the wall is open. Recenters on all notes (or origin when empty). Your pan/zoom per board is remembered in the browser.
 

internal/httpapi/web/dist/dialogs/wall-viewport-nav.js

@@ -5,6 +5,9 @@ const WHEEL_ZOOM_FACTOR = 1.08;
 // Approximate pixel sizes for line/page wheel modes (Firefox, some mice).
 const WHEEL_LINE_PX = 16;
 const WHEEL_PAGE_PX = 800;
+// Arrow-key pan step (screen px). Shift pans in coarse steps.
+const ARROW_PAN_STEP_PX = 64;
+const ARROW_PAN_STEP_COARSE_PX = ARROW_PAN_STEP_PX * 4;
 /** Normalize wheel deltas to pixels regardless of deltaMode. */
 function wheelPixels(ev) {
     const unit = ev.deltaMode === WheelEvent.DOM_DELTA_LINE
@@ -45,6 +48,37 @@ function onKeyDown(ev) {
     ev.preventDefault();
     spaceHeld = true;
 }
+// Arrow keys pan the canvas (additive to wheel / Space+drag / middle-drag).
+// Direction = the way the viewport moves toward content, matching scroll-to-pan.
+function onArrowKeyDown(ev, isOpen) {
+    if (ev.ctrlKey || ev.metaKey || ev.altKey)
+        return;
+    let dx = 0;
+    let dy = 0;
+    const step = ev.shiftKey ? ARROW_PAN_STEP_COARSE_PX : ARROW_PAN_STEP_PX;
+    switch (ev.key) {
+        case "ArrowRight":
+            dx = -step;
+            break;
+        case "ArrowLeft":
+            dx = step;
+            break;
+        case "ArrowDown":
+            dy = -step;
+            break;
+        case "ArrowUp":
+            dy = step;
+            break;
+        default:
+            return;
+    }
+    if (!isOpen())
+        return;
+    if (isNavigationSuppressed(ev.target))
+        return;
+    ev.preventDefault();
+    panBy(dx, dy);
+}
 function onKeyUp(ev) {
     if (ev.code !== "Space")
         return;
@@ -106,11 +140,12 @@ function bindPanPointer(surface, signal, shouldStart, onActiveChange) {
  * Bind wheel / keyboard / space+drag / middle-drag pan on the wall surface.
  * All listeners abort when `signal` fires (wall teardown).
  */
-export function bindWallNavigation(surface, signal) {
+export function bindWallNavigation(surface, signal, isOpen = () => true) {
     const opts = { signal, passive: false };
     surface.addEventListener("wheel", onWheel, opts);
     window.addEventListener("keydown", onKeyDown, { signal });
     window.addEventListener("keyup", onKeyUp, { signal });
+    window.addEventListener("keydown", (ev) => onArrowKeyDown(ev, isOpen), { signal });
     surface.addEventListener("blur", onBlur, { signal, capture: true });
     window.addEventListener("blur", onBlur, { signal });
     bindPanPointer(surface, signal, (ev) => ev.button === 1, (active) => {
@@ -124,6 +159,10 @@ export function bindWallNavigation(surface, signal) {
 export function isSpacePanArmed() {
     return spaceHeld;
 }
+/** For tests: drive the arrow-key pan handler directly. */
+export function __onArrowKeyDownForTest(ev, isOpen = () => true) {
+    onArrowKeyDown(ev, isOpen);
+}
 /** For tests: whether space-to-pan is armed. */
 export function __isSpaceHeldForTest() {
     return spaceHeld;

internal/httpapi/web/dist/dialogs/wall.js

@@ -73,7 +73,7 @@ export async function openWallDialog(opts) {
     wallSurface.classList.toggle("wall-surface--readonly", !canEdit);
     const content = ensureWallContent(wallSurface);
     initWallViewport(wallSurface, content, opts.slug);
-    bindWallNavigation(wallSurface, state.abort.signal);
+    bindWallNavigation(wallSurface, state.abort.signal, () => dialog.open);
     renderSurface();
     if (closeWallBtn) {
         closeWallBtn.addEventListener("click", () => dialog.close(), { signal: state.abort.signal });

internal/httpapi/web/modules/dialogs/wall-viewport-nav.test.ts

@@ -0,0 +1,92 @@
+// @vitest-environment happy-dom
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  ensureWallContent,
+  getViewportState,
+  initWallViewport,
+  teardownWallViewport,
+} from "./wall-viewport.js";
+import { __onArrowKeyDownForTest } from "./wall-viewport-nav.js";
+import { rect } from "./wall-test-harness.js";
+
+const STEP = 64;
+const COARSE = STEP * 4;
+
+function arrow(key: string, extra: Partial<KeyboardEventInit> = {}): KeyboardEvent {
+  return new KeyboardEvent("keydown", { key, bubbles: true, cancelable: true, ...extra });
+}
+
+describe("wall-viewport-nav arrow pan", () => {
+  let surface: HTMLElement;
+
+  beforeEach(() => {
+    document.body.innerHTML = "";
+    surface = document.createElement("div");
+    surface.id = "wallSurface";
+    document.body.appendChild(surface);
+    surface.getBoundingClientRect = () => rect(0, 0, 800, 600);
+    initWallViewport(surface, ensureWallContent(surface), "nav-proj");
+  });
+
+  afterEach(() => {
+    teardownWallViewport();
+    localStorage.clear();
+  });
+
+  it("ArrowRight pans content left (negative panX) by one step", () => {
+    __onArrowKeyDownForTest(arrow("ArrowRight"));
+    expect(getViewportState().panX).toBe(-STEP);
+  });
+
+  it("ArrowLeft pans content right (positive panX)", () => {
+    __onArrowKeyDownForTest(arrow("ArrowLeft"));
+    expect(getViewportState().panX).toBe(STEP);
+  });
+
+  it("ArrowDown / ArrowUp pan vertically", () => {
+    __onArrowKeyDownForTest(arrow("ArrowDown"));
+    expect(getViewportState().panY).toBe(-STEP);
+    __onArrowKeyDownForTest(arrow("ArrowUp"));
+    expect(getViewportState().panY).toBe(0);
+  });
+
+  it("Shift pans in coarse steps", () => {
+    __onArrowKeyDownForTest(arrow("ArrowRight", { shiftKey: true }));
+    expect(getViewportState().panX).toBe(-COARSE);
+  });
+
+  it("calls preventDefault when it pans", () => {
+    const ev = arrow("ArrowRight");
+    __onArrowKeyDownForTest(ev);
+    expect(ev.defaultPrevented).toBe(true);
+  });
+
+  it("does nothing when the wall is closed", () => {
+    __onArrowKeyDownForTest(arrow("ArrowRight"), () => false);
+    expect(getViewportState().panX).toBe(0);
+  });
+
+  it("is suppressed while editing a note", () => {
+    const note = document.createElement("div");
+    note.className = "wall-note wall-note--editing";
+    const ta = document.createElement("textarea");
+    note.appendChild(ta);
+    surface.appendChild(note);
+    const ev = arrow("ArrowRight");
+    Object.defineProperty(ev, "target", { value: ta });
+    __onArrowKeyDownForTest(ev);
+    expect(getViewportState().panX).toBe(0);
+  });
+
+  it("is ignored with ctrl/meta/alt modifiers", () => {
+    __onArrowKeyDownForTest(arrow("ArrowRight", { ctrlKey: true }));
+    __onArrowKeyDownForTest(arrow("ArrowRight", { metaKey: true }));
+    __onArrowKeyDownForTest(arrow("ArrowRight", { altKey: true }));
+    expect(getViewportState().panX).toBe(0);
+  });
+
+  it("ignores non-arrow keys", () => {
+    __onArrowKeyDownForTest(arrow("a"));
+    expect(getViewportState()).toEqual({ panX: 0, panY: 0, zoom: 1 });
+  });
+});

internal/httpapi/web/modules/dialogs/wall-viewport-nav.ts

@@ -15,6 +15,9 @@ const WHEEL_ZOOM_FACTOR = 1.08;
 // Approximate pixel sizes for line/page wheel modes (Firefox, some mice).
 const WHEEL_LINE_PX = 16;
 const WHEEL_PAGE_PX = 800;
+// Arrow-key pan step (screen px). Shift pans in coarse steps.
+const ARROW_PAN_STEP_PX = 64;
+const ARROW_PAN_STEP_COARSE_PX = ARROW_PAN_STEP_PX * 4;
 
 /** Normalize wheel deltas to pixels regardless of deltaMode. */
 function wheelPixels(ev: WheelEvent): { dx: number; dy: number } {
@@ -59,6 +62,35 @@ function onKeyDown(ev: KeyboardEvent): void {
   spaceHeld = true;
 }
 
+// Arrow keys pan the canvas (additive to wheel / Space+drag / middle-drag).
+// Direction = the way the viewport moves toward content, matching scroll-to-pan.
+function onArrowKeyDown(ev: KeyboardEvent, isOpen: () => boolean): void {
+  if (ev.ctrlKey || ev.metaKey || ev.altKey) return;
+  let dx = 0;
+  let dy = 0;
+  const step = ev.shiftKey ? ARROW_PAN_STEP_COARSE_PX : ARROW_PAN_STEP_PX;
+  switch (ev.key) {
+    case "ArrowRight":
+      dx = -step;
+      break;
+    case "ArrowLeft":
+      dx = step;
+      break;
+    case "ArrowDown":
+      dy = -step;
+      break;
+    case "ArrowUp":
+      dy = step;
+      break;
+    default:
+      return;
+  }
+  if (!isOpen()) return;
+  if (isNavigationSuppressed(ev.target)) return;
+  ev.preventDefault();
+  panBy(dx, dy);
+}
+
 function onKeyUp(ev: KeyboardEvent): void {
   if (ev.code !== "Space") return;
   spaceHeld = false;
@@ -139,12 +171,17 @@ function bindPanPointer(
  * Bind wheel / keyboard / space+drag / middle-drag pan on the wall surface.
  * All listeners abort when `signal` fires (wall teardown).
  */
-export function bindWallNavigation(surface: HTMLElement, signal: AbortSignal): void {
+export function bindWallNavigation(
+  surface: HTMLElement,
+  signal: AbortSignal,
+  isOpen: () => boolean = () => true,
+): void {
   const opts = { signal, passive: false as const };
 
   surface.addEventListener("wheel", onWheel, opts);
   window.addEventListener("keydown", onKeyDown, { signal });
   window.addEventListener("keyup", onKeyUp, { signal });
+  window.addEventListener("keydown", (ev) => onArrowKeyDown(ev, isOpen), { signal });
   surface.addEventListener("blur", onBlur, { signal, capture: true });
   window.addEventListener("blur", onBlur, { signal });
 
@@ -172,6 +209,11 @@ export function isSpacePanArmed(): boolean {
   return spaceHeld;
 }
 
+/** For tests: drive the arrow-key pan handler directly. */
+export function __onArrowKeyDownForTest(ev: KeyboardEvent, isOpen: () => boolean = () => true): void {
+  onArrowKeyDown(ev, isOpen);
+}
+
 /** For tests: whether space-to-pan is armed. */
 export function __isSpaceHeldForTest(): boolean {
   return spaceHeld;

internal/httpapi/web/modules/dialogs/wall.ts

@@ -140,7 +140,7 @@ export async function openWallDialog(opts: OpenWallDialogOptions): Promise<void>
   wallSurface.classList.toggle("wall-surface--readonly", !canEdit);
   const content = ensureWallContent(wallSurface);
   initWallViewport(wallSurface, content, opts.slug);
-  bindWallNavigation(wallSurface, state.abort.signal);
+  bindWallNavigation(wallSurface, state.abort.signal, () => dialog.open);
   renderSurface();
 
   if (closeWallBtn) {