Public: anyone can read this; the crew can change it.

small: the map pans with arrow keys and zooms with + and −, and says what is on screen in text for a screen reader #12784

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

torque/forge:torque/12755-small-the-map-pans-with-arrow-keys-and-z → main 5 commits fork 2 threads · 2 unresolved

  • Merged. torque/12755-small-the-map-pans-with-arrow-keys-and-z was merged into main as b82c3d7.

Review

Sign in to review this change.
4 files changed +168 −0
docs/features/map.md +9
@@ -8,3 +8,12 @@
88 `?lane=` is `owner/name` made of letters, digits, `.`, `_` and `-`, at most 200 characters; anything else, an unknown lane, or one you may not see draws nothing and the page is the light one. The test in `test/map.test.ts` holds the first screen under 50 KB.
99
1010 The other doors keep the whole graph: `/api/v1/map`, the MCP map tools and the terminal map return every lane, since a program asks for data, not a first paint.
11
12 ## Keyboard and screen reader (#12755)
13
14 Focus a map (click it or Tab to it) and it answers keys, only while focus is inside that map and not in a field, and never with Ctrl, ⌘ or Alt held:
15
16 - **Arrow keys** pan the drawing by 80 px per press, at any zoom.
17 - **`+`** (or `=`) zooms in, **`-`** zooms out, **`0`** fits the drawing again.
18
19 A polite live line under the map (`data-map-live`) says what is on screen after the view settles (400 ms after the last key): `Showing 3 of 12 issues`, counting the cards that overlap the visible frame. The focused map has an accent outline. The table of keys is `src/web/map_keys.ts`; the page script embeds its functions, so the tests run the same code.
src/web/map_keys.ts added +58
@@ -0,0 +1,58 @@
1 /**
2 * The keys the map answers while it is focused: one table, read by the page
3 * script and by the test. They act only inside `.map-canvas`, so they never
4 * meet the shell's global keys (which skip a key someone already handled).
5 */
6
7 type MapAction = "pan-left" | "pan-right" | "pan-up" | "pan-down" | "zoom-in" | "zoom-out" | "fit";
8
9 /** Pixels one arrow press pans the drawing by (screen pixels, at any zoom). */
10 export const PAN_STEP = 80;
11 /** Milliseconds after the last pan or zoom before the live line is rewritten. */
12 export const ANNOUNCE_DEBOUNCE_MS = 400;
13
14 export const MAP_KEYS: Readonly<Record<string, MapAction>> = {
15 ArrowLeft: "pan-left",
16 ArrowRight: "pan-right",
17 ArrowUp: "pan-up",
18 ArrowDown: "pan-down",
19 "+": "zoom-in",
20 "=": "zoom-in",
21 "-": "zoom-out",
22 "0": "fit",
23 };
24
25 /*
26 * The functions below are pure and self-contained (no closure over module
27 * state): the page script embeds them with `.toString()`, and the test calls
28 * the very same functions with real input.
29 */
30
31 /** The action a key press means, or null: modified keys and unknown keys mean nothing. */
32 export function mapAction(
33 keys: Readonly<Record<string, string>>,
34 key: string,
35 ctrl: boolean,
36 meta: boolean,
37 alt: boolean,
38 ): string | null {
39 if (ctrl || meta || alt) return null;
40 return Object.prototype.hasOwnProperty.call(keys, key) ? keys[key]! : null;
41 }
42
43 /** Whether a key pressed on this element is being typed into a field, and so is not ours. */
44 export function typesIntoField(tag: string | undefined, editable: boolean | undefined): boolean {
45 return tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT" || editable === true;
46 }
47
48 /** How many rectangles overlap the box at all (each is [left, top, right, bottom]). */
49 export function countInView(rects: number[][], box: number[]): number {
50 let n = 0;
51 for (const r of rects) if (r[2]! > box[0]! && r[0]! < box[2]! && r[3]! > box[1]! && r[1]! < box[3]!) n++;
52 return n;
53 }
54
55 /** The sentence the live region says: "Showing 3 of 12 issues". */
56 export function showingLine(inView: number, total: number): string {
57 return "Showing " + inView + " of " + total + " issue" + (total === 1 ? "" : "s");
58 }
src/web/pages/map.ts +39
@@ -19,6 +19,7 @@
1919 * can see, one lane each.
2020 */
2121
22 import { ANNOUNCE_DEBOUNCE_MS, countInView, MAP_KEYS, mapAction, PAN_STEP, showingLine, typesIntoField } from "../map_keys.ts";
2223 import { setCookie } from "../../auth/cookies.ts";
2324 import { mayDirectCrew } from "../../crew/direct.ts";
2425 import { faceAt } from "../pixel.ts";
@@ -865,6 +866,9 @@ export function drawMap(
865866 data-w="${g.width}"
866867 data-h="${g.height}"
867868 data-cap="${options.cap ?? 0.72}"
869 tabindex="0"
870 role="region"
871 aria-label="Map of ${repo.name}. Arrow keys pan, plus and minus zoom, 0 fits."
868872 data-cuts="${Array.from({ length: placed.levels }, (_, l) =>
869873 l === placed.levels - 1 ? g.height : g.y(l) + H + 12,
870874 ).join(",")}"
@@ -892,6 +896,7 @@ export function drawMap(
892896 )}
893897 ${placed.nodes.map((n) => node(base, n, g, emphasis, issueHref))}
894898 </svg>
899 <p class="sr-only" data-map-live aria-live="polite" role="status"></p>
895900 <div class="bar js-only" role="group" aria-label="Zoom">
896901 <button
897902 type="button"
@@ -1161,6 +1166,7 @@ export const mapCss = /* css */ `
11611166 .map-node:hover .map-card { stroke: var(--border-strong); }
11621167 .map-node[data-state="working"]:hover .map-card { stroke: var(--accent); }
11631168 .map-node:focus-visible .map-card { stroke: var(--accent); stroke-width: 2; }
1169 .map-canvas:focus-visible { outline: 2px solid var(--accent); outline-offset: -2px; }
11641170 /* A soft outer ring, static: any animation inside a large inline SVG
11651171 repaints the whole drawing every frame, whatever property it touches. */
11661172 .map-breath { fill: none; stroke: var(--accent); stroke-width: 1.5; opacity: .35; }
@@ -1223,6 +1229,11 @@ export const mapCss = /* css */ `
12231229 */
12241230 export const mapViewJs = /* js */ `
12251231 (function () {
1232 var KEYS = ${JSON.stringify(MAP_KEYS)}, STEP = ${PAN_STEP}, QUIET = ${ANNOUNCE_DEBOUNCE_MS};
1233 ${mapAction.toString()}
1234 ${typesIntoField.toString()}
1235 ${countInView.toString()}
1236 ${showingLine.toString()}
12261237 var MIN = 0.35, MAX = 2.5;
12271238 var views = {};
12281239 var folds = {};
@@ -1231,6 +1242,21 @@ export const mapViewJs = /* js */ `
12311242 var svg = canvas.querySelector('.map-svg'), v = views[canvas.id];
12321243 if (!svg || !v) return;
12331244 svg.setAttribute('viewBox', v.x.toFixed(2) + ' ' + v.y.toFixed(2) + ' ' + (v.cw / v.k).toFixed(2) + ' ' + (v.ch / v.k).toFixed(2));
1245 if (v.touched) announce(canvas);
1246 }
1247 var timers = {};
1248 function announce(canvas) {
1249 clearTimeout(timers[canvas.id]);
1250 timers[canvas.id] = setTimeout(function () {
1251 var live = canvas.querySelector('[data-map-live]'), nodes = canvas.querySelectorAll('.map-node');
1252 if (!live) return;
1253 var c = canvas.getBoundingClientRect(), rects = [];
1254 Array.prototype.forEach.call(nodes, function (el) {
1255 var r = el.getBoundingClientRect();
1256 rects.push([r.left, r.top, r.right, r.bottom]);
1257 });
1258 live.textContent = showingLine(countInView(rects, [c.left, c.top, c.right, c.bottom]), nodes.length);
1259 }, QUIET);
12341260 }
12351261 function setup(canvas, refit) {
12361262 if (!canvas.id || !canvas.querySelector('.map-svg') || !canvas.clientWidth) return;
@@ -1326,6 +1352,19 @@ export const mapViewJs = /* js */ `
13261352 var what = tool.getAttribute('data-map');
13271353 if (what === 'fit') setup(canvas, true); else zoom(canvas, what === 'in' ? 1.25 : 0.8);
13281354 }, true);
1355 document.addEventListener('keydown', function (e) {
1356 var canvas = canvasOf(e);
1357 if (!canvas || !views[canvas.id] || e.defaultPrevented) return;
1358 var t = e.target;
1359 if (typesIntoField(t && t.tagName, t && t.isContentEditable)) return;
1360 var what = mapAction(KEYS, e.key, e.ctrlKey, e.metaKey, e.altKey);
1361 if (!what) return;
1362 e.preventDefault();
1363 if (what === 'fit') { setup(canvas, true); views[canvas.id].touched = true; announce(canvas); }
1364 else if (what === 'zoom-in') zoom(canvas, 1.25);
1365 else if (what === 'zoom-out') zoom(canvas, 0.8);
1366 else pan(canvas, what === 'pan-left' ? STEP : what === 'pan-right' ? -STEP : 0, what === 'pan-up' ? STEP : what === 'pan-down' ? -STEP : 0);
1367 });
13291368 document.addEventListener('wheel', function (e) {
13301369 var canvas = canvasOf(e);
13311370 if (!canvas || !views[canvas.id] || !(e.ctrlKey || e.metaKey)) return;
test/map-keys-pan.test.ts added +62
@@ -0,0 +1,62 @@
1 /**
2 * The map's keyboard path: each key maps to its action, typing is left alone,
3 * and the emitted script and markup carry it (#12755).
4 */
5 import { expect, test } from "bun:test";
6 import { countInView, MAP_KEYS, mapAction, PAN_STEP, showingLine, typesIntoField } from "../src/web/map_keys.ts";
7 import { mapViewJs } from "../src/web/pages/map.ts";
8
9 test("each key maps to its action", () => {
10 expect(MAP_KEYS).toEqual({
11 ArrowLeft: "pan-left",
12 ArrowRight: "pan-right",
13 ArrowUp: "pan-up",
14 ArrowDown: "pan-down",
15 "+": "zoom-in",
16 "=": "zoom-in",
17 "-": "zoom-out",
18 "0": "fit",
19 });
20 });
21
22 test("the emitted script carries the table, the step and the pure helpers", () => {
23 expect(mapViewJs).toContain(JSON.stringify(MAP_KEYS));
24 expect(mapViewJs).toContain(`STEP = ${PAN_STEP}`);
25 for (const f of [mapAction, typesIntoField, countInView, showingLine]) expect(mapViewJs).toContain(f.toString());
26 expect(mapViewJs).toContain("data-map-live");

These toContain checks on script text would still pass if the logic were wrong. Test the count and the field guard as pure functions with real input.

27 });
28
29 test("mapAction: keys map, modified and unknown keys are left alone", () => {
30 expect(mapAction(MAP_KEYS, "ArrowLeft", false, false, false)).toBe("pan-left");
31 expect(mapAction(MAP_KEYS, "=", false, false, false)).toBe("zoom-in");
32 expect(mapAction(MAP_KEYS, "0", false, false, false)).toBe("fit");
33 expect(mapAction(MAP_KEYS, "-", true, false, false)).toBeNull();
34 expect(mapAction(MAP_KEYS, "+", false, true, false)).toBeNull();
35 expect(mapAction(MAP_KEYS, "ArrowUp", false, false, true)).toBeNull();
36 expect(mapAction(MAP_KEYS, "a", false, false, false)).toBeNull();
37 expect(mapAction(MAP_KEYS, "constructor", false, false, false)).toBeNull();
38 });
39
40 test("typesIntoField: fields and editable text are typing, the rest is not", () => {
41 expect(typesIntoField("INPUT", false)).toBe(true);
42 expect(typesIntoField("TEXTAREA", undefined)).toBe(true);
43 expect(typesIntoField("SELECT", false)).toBe(true);
44 expect(typesIntoField("DIV", true)).toBe(true);
45 expect(typesIntoField("DIV", false)).toBe(false);
46 expect(typesIntoField(undefined, undefined)).toBe(false);
47 });
48
49 test("countInView counts overlapping rectangles; showingLine words it", () => {
50 const box = [0, 0, 100, 100];
51 const rects = [[10, 10, 50, 50], [90, 90, 150, 150], [100, 0, 140, 40], [-60, 20, 0, 60], [20, 120, 60, 160], [-10, -10, 1, 1]];
52 expect(countInView(rects, box)).toBe(3);
53 expect(countInView([], box)).toBe(0);
54 expect(showingLine(3, 12)).toBe("Showing 3 of 12 issues");
55 expect(showingLine(1, 1)).toBe("Showing 1 of 1 issue");
56 expect(showingLine(0, 0)).toBe("Showing 0 of 0 issues");
57 });
58
59 test("the canvas has a visible focus ring of its own", async () => {
60 const src = await Bun.file(new URL("../src/web/pages/map.ts", import.meta.url)).text();
61 expect(src).toContain(".map-canvas:focus-visible { outline: 2px solid var(--accent); outline-offset: -2px; }");
62 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs