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
Check · Review · Land · Live done — Landed and live in production.
torque/forge:torque/12755-small-the-map-pans-with-arrow-keys-and-z → main 5 commits fork 2 threads · 2 unresolved
4 files
changed +168
−0
docs/features/map.md +9
| @@ -8,3 +8,12 @@ | ||
| 8 | 8 | `?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. |
| 9 | 9 | |
| 10 | 10 | 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 @@ | ||
| 19 | 19 | * can see, one lane each. |
| 20 | 20 | */ |
| 21 | 21 | |
| 22 | import { ANNOUNCE_DEBOUNCE_MS, countInView, MAP_KEYS, mapAction, PAN_STEP, showingLine, typesIntoField } from "../map_keys.ts"; | |
| 22 | 23 | import { setCookie } from "../../auth/cookies.ts"; |
| 23 | 24 | import { mayDirectCrew } from "../../crew/direct.ts"; |
| 24 | 25 | import { faceAt } from "../pixel.ts"; |
| @@ -865,6 +866,9 @@ export function drawMap( | ||
| 865 | 866 | data-w="${g.width}" |
| 866 | 867 | data-h="${g.height}" |
| 867 | 868 | 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." | |
| 868 | 872 | data-cuts="${Array.from({ length: placed.levels }, (_, l) => |
| 869 | 873 | l === placed.levels - 1 ? g.height : g.y(l) + H + 12, |
| 870 | 874 | ).join(",")}" |
| @@ -892,6 +896,7 @@ export function drawMap( | ||
| 892 | 896 | )} |
| 893 | 897 | ${placed.nodes.map((n) => node(base, n, g, emphasis, issueHref))} |
| 894 | 898 | </svg> |
| 899 | <p class="sr-only" data-map-live aria-live="polite" role="status"></p> | |
| 895 | 900 | <div class="bar js-only" role="group" aria-label="Zoom"> |
| 896 | 901 | <button |
| 897 | 902 | type="button" |
| @@ -1161,6 +1166,7 @@ export const mapCss = /* css */ ` | ||
| 1161 | 1166 | .map-node:hover .map-card { stroke: var(--border-strong); } |
| 1162 | 1167 | .map-node[data-state="working"]:hover .map-card { stroke: var(--accent); } |
| 1163 | 1168 | .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; } | |
| 1164 | 1170 | /* A soft outer ring, static: any animation inside a large inline SVG |
| 1165 | 1171 | repaints the whole drawing every frame, whatever property it touches. */ |
| 1166 | 1172 | .map-breath { fill: none; stroke: var(--accent); stroke-width: 1.5; opacity: .35; } |
| @@ -1223,6 +1229,11 @@ export const mapCss = /* css */ ` | ||
| 1223 | 1229 | */ |
| 1224 | 1230 | export const mapViewJs = /* js */ ` |
| 1225 | 1231 | (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()} | |
| 1226 | 1237 | var MIN = 0.35, MAX = 2.5; |
| 1227 | 1238 | var views = {}; |
| 1228 | 1239 | var folds = {}; |
| @@ -1231,6 +1242,21 @@ export const mapViewJs = /* js */ ` | ||
| 1231 | 1242 | var svg = canvas.querySelector('.map-svg'), v = views[canvas.id]; |
| 1232 | 1243 | if (!svg || !v) return; |
| 1233 | 1244 | 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); | |
| 1234 | 1260 | } |
| 1235 | 1261 | function setup(canvas, refit) { |
| 1236 | 1262 | if (!canvas.id || !canvas.querySelector('.map-svg') || !canvas.clientWidth) return; |
| @@ -1326,6 +1352,19 @@ export const mapViewJs = /* js */ ` | ||
| 1326 | 1352 | var what = tool.getAttribute('data-map'); |
| 1327 | 1353 | if (what === 'fit') setup(canvas, true); else zoom(canvas, what === 'in' ? 1.25 : 0.8); |
| 1328 | 1354 | }, 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 | }); | |
| 1329 | 1368 | document.addEventListener('wheel', function (e) { |
| 1330 | 1369 | var canvas = canvasOf(e); |
| 1331 | 1370 | 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"); | |
| 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 | }); |
new above
offline
These
toContainchecks on script text would still pass if the logic were wrong. Test the count and the field guard as pure functions with real input.