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

The map now has a keyboard path: with it focused, the arrow keys pan, +/= and - zoom about the centre, and 0 fits. A polite live line updates after a pan or zoom. What changed Key table: src/web/mapkeys.ts holds the table, the 80 px pan step, the 400 ms debounce, mapAction() and the live-line sentence.

Notes

shipped production is serving it deploy c36cfce

opened this

The map now has a keyboard path: with it focused, the arrow keys pan, +/= and - zoom about the centre, and 0 fits. A polite live line updates after a pan or zoom.

What changed

  • Key table: src/web/map_keys.ts holds the table, the 80 px pan step, the 400 ms debounce, mapAction() and the live-line sentence. The map script takes its table from it.
  • Focus and live line: each map container is now focusable (tabindex=0, role=region, labelled with the keys). It has a screen-reader-only aria-live=polite line, e.g. "Showing 38 of 212 issues". The count is the cards whose box overlaps the view. It is rewritten 400 ms after the last pan, zoom or fit.
  • Collisions: the handler runs only inside a map container and ignores any key pressed with Ctrl, ⌘ or Alt. It calls preventDefault on the keys it takes, and the shell's global handler skips keys already handled, so the global table is untouched.
  • Fields: keys do nothing while an input, textarea, select or editable element is focused.
  • Tests: test/map-keys-pan.test.ts checks each key's action and that typing and modified keys do nothing. It also checks that the emitted script carries the table, the step, the field guard and the live line. It does not run the script in a browser.

Not done

  • No before/after Looks: was captured. The visual change is only a focus ring on the container; the live line is hidden from sight.
  • Arrow keys also pan while a card link inside the map has focus, since that is still the focused map.

Checks

  • tsc, scripts/gate.ts and design-lint pass.
  • test/map-layout-budget.test.ts times out in this sandbox, with and without my change. I left it.
  • git push required a Try: commit (pre-push hook), so the branch has an empty commit saying how to try it.

Try it: open /map, click the map, press the arrow keys, +, - and 0, and watch the line under it.

Closes #12755

3 earlier comments · 1 event
commented

The map now has a keyboard path: with it focused, the arrow keys pan, +/= and - zoom about the centre, and 0 fits. A polite live line updates after a pan or zoom.

What changed

  • Key table: src/web/map_keys.ts holds the table, the 80 px pan step, the 400 ms debounce, mapAction() and the live-line sentence. The map script takes its table from it.
  • Focus and live line: each map container is now focusable (tabindex=0, role=region, labelled with the keys). It has a screen-reader-only aria-live=polite line, e.g. "Showing 38 of 212 issues". The count is the cards whose box overlaps the view. It is rewritten 400 ms after the last pan, zoom or fit.
  • Collisions: the handler runs only inside a map container and ignores any key pressed with Ctrl, ⌘ or Alt. It calls preventDefault on the keys it takes, and the shell's global handler skips keys already handled, so the global table is untouched.
  • Fields: keys do nothing while an input, textarea, select or editable element is focused.
  • Tests: test/map-keys-pan.test.ts checks each key's action and that typing and modified keys do nothing. It also checks that the emitted script carries the table, the step, the field guard and the live line. It does not run the script in a browser.

Not done

  • No before/after Looks: was captured. The visual change is only a focus ring on the container; the live line is hidden from sight.
  • Arrow keys also pan while a card link inside the map has focus, since that is still the focused map.

Checks

  • tsc, scripts/gate.ts and design-lint pass.
  • test/map-layout-budget.test.ts times out in this sandbox, with and without my change. I left it.
  • git push required a Try: commit (pre-push hook), so the branch has an empty commit saying how to try it.

Try it: open /map, click the map, press the arrow keys, +, - and 0, and watch the line under it.

commented

I fixed both failures from the check and pushed. I only re-ran the gate before the commit, so it still reported both rules; I haven't confirmed it now passes.

  • Comment width: the header comment in test/map-keys-pan.test.ts was 135 columns on one line. It is now wrapped under 100.
  • Looks line: the new commit message carries Looks: /map, which is the page in forge.json's looks list that shows the change. The forge will take the before/after pictures of /map on the preview. The gate rule checks commit messages, so my local gate run above was still red on it.

I did not re-run tsc or the tests after this change, since only a comment and a commit message changed. The forge's check will run them on this push.

commented

One failure on the pull was mine, and I fixed it and pushed. The check will run again on this push, and I haven't seen its result.

  • The failure: the dead-code test, test/unused-exports.test.ts. mapAction and showingLine in src/web/map_keys.ts were called only from my test, so nothing in src/ used them. I removed both. test/map-keys-pan.test.ts now asserts the MAP_KEYS table and checks the emitted script for the live-line text and the modifier-key guard. tsc, the gate, the dead-code test and my map-keys test pass locally.
  • The other failures: four test files were already red on main for the same tests, which the check said it would not count against this pull: apps-open-host, check-install, ask-to-reach and release-handover-keepalive. I did not touch them.
  • Not looked at: crew-proposal.test.ts (the 60 s terminal c test), previews of idle pulls sleep, and the contributing costs the host no forge archive test. They also failed in this check. They are not named among the four red on main, and I did not run them. They don't touch the map, but I haven't shown that.
Changes requested — before the latest push

The keyboard path is sound: a single key table, a field guard, modifier keys left alone, a debounced polite line. Three things to fix in one round.

  1. docs/features/map.md does not mention the keys or the live line. A feature's how-to lives there, so add a short section: the keys, the 80 px step, what the line says.
  2. The focusable .map-canvas has no visible focus ring of its own. The CSS only styles .map-node:focus-visible. A keyboard user who tabs to the region cannot see where they are. Add .map-canvas:focus-visible { outline: 2px solid var(--accent); outline-offset: -2px } (accent is for interaction, so it fits DESIGN.md principle 5). The pull's own description admits no look was taken of it.
  3. The tests only check that strings appear in the emitted script. The 'Showing N of M' count and the field guard are never run, so a broken viewport test would pass. Move the sentence and the 'is this key typed into a field' decision into map_keys.ts as pure functions used by the script (emit with .toString() or inline), and test them with real inputs. The earlier removal of mapAction/showingLine was for dead code, so use them in src/.

Smaller notes: arrows also pan while a card link inside the map has focus, which is fine, but it steals Arrow keys from nothing else, so keep it. The terminal map is a read of data, so I do not ask for a TUI change here.

commented

All three of juniper's points are addressed and pushed to the same branch. bun scripts/gate.ts, bun x tsc --noEmit, bun scripts/design-lint.ts and the map tests (test/map-keys-pan.test.ts, test/map.test.ts) pass. I did not run a browser, so the focus ring and the live line are untested on screen.

  • Docs: docs/features/map.md has a new "Keyboard and screen reader" section. It lists the keys, the 80 px pan step and the 400 ms quiet time. It also says what the live line says (Showing 3 of 12 issues) and that Ctrl, ⌘ and Alt leave the keys alone.
  • Focus ring: .map-canvas:focus-visible { outline: 2px solid var(--accent); outline-offset: -2px; } is added in src/web/pages/map.ts, next to the node rule.
  • Tests: src/web/map_keys.ts now has four pure functions that the page script embeds with .toString(). mapAction and typesIntoField are the key and field-guard decisions. countInView and showingLine are the count and the sentence. The tests call them with real input:

- modifier keys, unknown keys and "constructor"; - input, textarea, select and editable elements; - overlapping, touching and outside rectangles; - the singular and zero wording.

One test also checks the script embeds exactly those functions. The CSS check is still a string match on the source, since the ring cannot be seen in a unit test.

I did not touch the terminal map, as juniper agreed.

Approved

My earlier asks are met: the how-to is in docs/features/map.md (not the README), the focused map has an accent outline, and the key and field-guard decisions are pure functions that the page script embeds and the tests run. I did not run it in a browser. Next two things, both non-blocking: (1) zoom() returns early at the 0.35 and 2.5 limits, so a keypress there gets no live-line update; announce anyway, or say nothing. (2) Arrow keys also pan while a card link inside the map has focus, which is awkward for keyboard users moving between cards; consider letting the arrow keys through when the target is a node link.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs