Compare commits

..
Author SHA1 Message Date
Brent Vatne cefeb8059a Release 0.19.6 2026-10-17 20:44:52 -07:00
Brent Vatne 078902710b Capture iPhone Duo on EAS Simulator with eas simulator:control, for both controllers (#9)
Capture iPhone Duo on EAS Simulator with eas simulator:control, for both controllers

- eas-cli 25.2.0: app.approveUrlScheme after install, appearance.set for Argent on
  iOS EAS sessions, and springboard.restart as the last fold recovery step. The
  controller's own tools come first; these only fill what neither controller has.
- iPhone Duo on EAS: both controllers' folds are verified (Argent by its tree,
  agent-device by its screenshot) and recovered by restarting SpringBoard and
  folding again, once; never by stopping the session's tool-server.
- agent-device opens the app before folding on EAS, as it does locally.
- agent-device pinned to 0.21.29-nightly.20261018.74 for callstack/agent-device#3776,
  which stops @expo/ui sliders on a regular-width display from wedging its runner.
- A session EAS fails to start is replaced, up to five times within 30 minutes,
  with a growing wait, only when the failure is provably EAS's.
- doctor warns about Argent's single appearance only for Android EAS sessions.
2026-10-17 20:44:41 -07:00
Brent Vatne 46ff99aad1 Viewer: held keys repeat and glide, arrows enter the map, held modifiers show their keys, T and ⇧T (#10) 2026-10-17 18:52:55 -07:00
23 changed files with 663 additions and 101 deletions

No files matched your search

+2 -2
View File
@@ -1,12 +1,12 @@
{
"name": "@expo/explore",
"version": "0.19.5",
"version": "0.19.6",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "@expo/explore",
"version": "0.19.5",
"version": "0.19.6",
"license": "MIT",
"dependencies": {
"@expo/repack-app": "0.10.1",
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@expo/explore",
"version": "0.19.5",
"version": "0.19.6",
"description": "Source-driven mobile app maps, deterministic CI capture, and visual reviews",
"license": "MIT",
"type": "module",
+130 -9
View File
@@ -1491,8 +1491,19 @@ test("Esc closes the Inspector first, then deselects; arrows and hjkl walk the m
await expect(selected).toHaveCount(0);
await expect(page).toHaveURL(/\/map$/);
// Nothing selected: the arrows are not map moves.
await page.keyboard.press("ArrowDown");
// Nothing selected: ↓ enters the map at its top, as → enters Screens at its first card; held, it
// keeps walking down from there and stops where it is on release.
await page.keyboard.down("ArrowDown");
await expect(selected).toHaveCount(1);
const entered = await selected.getAttribute("data-id");
await expect.poll(() => selected.getAttribute("data-id"), { timeout: 4000 }).not.toBe(entered);
await page.keyboard.up("ArrowDown");
const walkedTo = await selected.getAttribute("data-id");
await page.waitForTimeout(500);
await expect(selected).toHaveAttribute("data-id", walkedTo!);
await page.keyboard.press("Escape");
await expect(page.locator(".right-panel")).toHaveCount(0);
await page.keyboard.press("Escape");
await expect(selected).toHaveCount(0);
await page.locator(".map-canvas .react-flow__node-screen .screen-screenshot-target").first().click();
@@ -1508,6 +1519,67 @@ test("Esc closes the Inspector first, then deselects; arrows and hjkl walk the m
await expect(selected).toHaveAttribute("data-id", child!);
});
test("a held key stops when Esc, another key or a dialog takes the keyboard; a menu keeps its own arrows", async ({ page }) => {
await page.goto("/map");
const selected = page.locator(".map-canvas .react-flow__node-screen.selected");
const inspector = page.locator(".right-panel");
const search = page.getByRole("dialog", { name: "Search Explore" });
const viewport = page.locator(".map-canvas .react-flow__viewport");
const mod = process.platform === "darwin" ? "Meta" : "Control";
// Nothing selected and a menu open: ← and → on its item are the menu's, not the map's.
await expect(selected).toHaveCount(0);
await page.locator(".zoom-button").click();
await expect(page.getByRole("menu")).toBeVisible();
await page.keyboard.press("ArrowDown");
await page.keyboard.press("ArrowLeft");
await page.keyboard.press("ArrowRight");
await expect(selected).toHaveCount(0);
await page.keyboard.press("Escape");
await expect(page.getByRole("menu")).toHaveCount(0);
// Esc mid-walk closes the Inspector, and the walk does not reopen it on its next step.
await page.locator(".map-canvas .react-flow__node-screen .screen-screenshot-target").first().click();
await expect(inspector).toBeVisible();
await page.keyboard.down("ArrowDown");
await page.keyboard.press("Escape");
await expect(inspector).toHaveCount(0);
await page.waitForTimeout(800);
await expect(inspector).toHaveCount(0);
await page.keyboard.up("ArrowDown");
// ⌘K mid-walk opens Search, and the selection behind it stays where it was.
await page.keyboard.down("ArrowDown");
await page.keyboard.press(`${mod}+k`);
await expect(search).toBeVisible();
const behind = await selected.getAttribute("data-id");
await page.waitForTimeout(800);
await expect(selected).toHaveAttribute("data-id", behind!);
await page.keyboard.up("ArrowDown");
await page.keyboard.press("Escape");
await expect(search).toHaveCount(0);
// A held + glides past the tap's one step and stops where it is on release.
const zoomNow = async () => (await readCanvasCamera(viewport)).zoom;
const before = await zoomNow();
await page.keyboard.down("Equal");
await expect.poll(zoomNow, { timeout: 4000 }).toBeGreaterThan(before * 1.2 * 1.2);
await page.keyboard.up("Equal");
const released = await zoomNow();
await page.waitForTimeout(300);
expect(await zoomNow()).toBeCloseTo(released, 3);
// Held −, then a click opens Search: the glide stops rather than zoom behind the dialog.
await page.keyboard.down("Minus");
await page.getByRole("button", { name: "Search", exact: true }).click();
await expect(search).toBeVisible();
await page.waitForTimeout(400);
const atOpen = await zoomNow();
await page.waitForTimeout(800);
expect(await zoomNow()).toBeCloseTo(atOpen, 3);
await page.keyboard.up("Minus");
});
test("a drag that starts on a transition edge pans the map", async ({ page }) => {
await page.goto("/map");
const viewport = page.locator(".map-canvas .react-flow__viewport");
@@ -2040,16 +2112,12 @@ test("canonicalizes the legacy Workspace route to Changes and reports the exact
if (entry.status === "unchanged") return total;
return total + (entry.currentScreenIds.length || entry.baselineScreenIds.length);
}, 0);
// The bottom bar's Compare button carries the count.
const badge = page.locator(".canvas-toolbar .toolbar-badge");
await expect(badge).toHaveText(String(expectedChanges));
const menu = await openChangesMenu(page);
await expect(menu.locator(".changes-panel-title .changes-panel-count")).toHaveText(String(expectedChanges));
// Without a baseline there is nothing to count. Compare still opens, and the view says why it is empty.
await page.goto("/map?baseline=none");
await expect(page).toHaveURL(/baseline=none/);
await expect(badge).toHaveCount(0);
const compare = page.getByRole("toolbar", { name: "Canvas tools" }).getByRole("button", { name: "Compare", exact: true });
await expect(compare).not.toHaveAttribute("aria-disabled", "true");
await compare.click();
@@ -2700,6 +2768,31 @@ test("drives the shell from the keyboard, and says so on hover", async ({ page }
}
await expect(page.getByRole("button", { name: "Comments", exact: true })).toHaveCount(0);
// A held modifier shows, on each button it makes a chord with, the key that completes it: ⇧ puts
// 1 on Fit canvas, ⌘ (Ctrl elsewhere) puts K on Search. Released, the hints go.
const hints = page.locator(".key-hint");
await expect(hints).toHaveCount(0);
await page.keyboard.down("Shift");
await expect(page.getByRole("button", { name: "Fit canvas" }).locator(".key-hint")).toHaveText("1");
await expect(page.getByRole("button", { name: "Center canvas" }).locator(".key-hint")).toHaveText("2");
await expect(page.getByRole("button", { name: "Search", exact: true }).locator(".key-hint")).toHaveCount(0);
await page.keyboard.up("Shift");
await expect(hints).toHaveCount(0);
await page.keyboard.down(mod);
await expect(page.getByRole("button", { name: "Search", exact: true }).locator(".key-hint")).toHaveText("K");
await expect(page.getByRole("button", { name: "Fit canvas" }).locator(".key-hint")).toHaveCount(0);
await page.keyboard.up(mod);
await expect(hints).toHaveCount(0);
// Focus that moves into a field by mouse, with ⇧ still down, takes the hints with it.
await page.keyboard.down("Shift");
await expect(page.getByRole("button", { name: "Fit canvas" }).locator(".key-hint")).toHaveText("1");
await page.getByRole("button", { name: "Search", exact: true }).click();
await expect(page.getByRole("dialog", { name: "Search Explore" })).toBeVisible();
await expect(hints).toHaveCount(0);
await page.keyboard.up("Shift");
await page.keyboard.press("Escape");
await expect(page.getByRole("dialog", { name: "Search Explore" })).toHaveCount(0);
// ⌘B opens and closes the Changes menu.
await page.keyboard.press(`${mod}+b`);
await expect(page.locator(".changes-menu")).toBeVisible();
@@ -2732,14 +2825,23 @@ test("drives the shell from the keyboard, and says so on hover", async ({ page }
await expect(page.locator(".tooltip-key")).toHaveText("C");
await page.getByRole("button", { name: "Expand inspector" }).hover();
await expect(page.locator(".tooltip-key")).toHaveText("I");
// The theme button has no key: it names the mode in force and nothing else.
// The theme button names the mode in force, and T is its key.
const themeButton = page.getByRole("button", { name: "Toggle theme" });
await themeButton.hover();
await expect(page.locator(".tooltip-content")).toContainText("Theme:");
await expect(page.locator(".tooltip-key")).toHaveCount(0);
await expect(page.locator(".tooltip-content")).toContainText("Theme: Auto");
await expect(page.locator(".tooltip-key")).toHaveText("T");
await page.mouse.move(0, 0);
const initialTheme = await page.locator("html").getAttribute("data-theme");
expect(initialTheme === "light" || initialTheme === "dark").toBe(true);
const otherTheme = initialTheme === "dark" ? "light" : "dark";
// T flips between dark and light from whatever Auto showed, and never steps back to Auto.
await page.keyboard.press("t");
await expect(page.locator("html")).toHaveAttribute("data-theme", otherTheme);
await page.keyboard.press("t");
await expect(page.locator("html")).toHaveAttribute("data-theme", initialTheme!);
await themeButton.hover();
await expect(page.locator(".tooltip-content")).toContainText(initialTheme === "dark" ? "Theme: Dark" : "Theme: Light");
await page.mouse.move(0, 0);
// The retired theme and inspector chords no longer answer.
await page.keyboard.press(`${mod}+Alt+t`);
await expect(page.locator("html")).toHaveAttribute("data-theme", initialTheme!);
@@ -4202,6 +4304,25 @@ test("desktop Compare: one command bar with the modes in it, even gaps to both b
for (let step = 1; step < before; step += 1) await page.keyboard.press("ArrowRight");
await expect(position).toHaveText(new RegExp(`^${before} of `));
// In Swipe, [ and ] nudge the divider; held, ] keeps going until it is released or at the edge.
await page.keyboard.press("2");
const divider = compare.getByRole("slider");
await expect(divider).toHaveAttribute("aria-valuenow", "50");
await page.keyboard.press("BracketLeft");
await expect(divider).toHaveAttribute("aria-valuenow", "45");
const dividerAt = async () => Number(await divider.getAttribute("aria-valuenow"));
await page.keyboard.down("BracketRight");
await expect(divider).toHaveAttribute("aria-valuenow", "50");
await expect.poll(dividerAt, { timeout: 4000 }).toBeGreaterThanOrEqual(65);
await page.keyboard.up("BracketRight");
const dividerHeld = await dividerAt();
await page.waitForTimeout(600);
expect(await dividerAt()).toBe(dividerHeld);
await page.keyboard.down("BracketRight");
await expect.poll(dividerAt, { timeout: 8000 }).toBe(100);
await page.keyboard.up("BracketRight");
await page.keyboard.press("1");
// The bar keeps one size whatever the route, so Next stays under the pointer: it can be clicked
// again and again through screens whose routes differ in length.
const nextButton = bar.getByRole("button", { name: "Next changed screen" });
+28
View File
@@ -0,0 +1,28 @@
import assert from "node:assert/strict";
import test from "node:test";
const { tsImport } = await import("tsx/esm/api");
const { heldKeyHint, shortcutModifiers } = await tsImport("../../viewer/src/utils/held-modifiers.ts", import.meta.url);
const { SHORTCUTS } = await tsImport("../../viewer/src/utils/shortcuts.ts", import.meta.url);
const held = (keys) => ({ shift: false, ctrl: false, meta: false, alt: false, ...keys });
test("holding a chord's modifiers shows the key that completes it; anything else shows nothing", () => {
assert.equal(heldKeyHint(SHORTCUTS.canvasByNumber.map, held({ ctrl: true }), true), "1");
assert.equal(heldKeyHint(SHORTCUTS.canvasByNumber.compare, held({ ctrl: true }), true), "3");
assert.equal(heldKeyHint(SHORTCUTS.camera.fit, held({ shift: true }), true), "1");
assert.equal(heldKeyHint(SHORTCUTS.appearance.app, held({ shift: true }), true), "T");
assert.equal(heldKeyHint(SHORTCUTS.canvasByNumber.map, held({ shift: true }), true), undefined, "the wrong modifier");
assert.equal(heldKeyHint(SHORTCUTS.canvasByNumber.map, held({ ctrl: true, shift: true }), true), undefined, "an extra modifier");
assert.equal(heldKeyHint(SHORTCUTS.canvas.map, held({ ctrl: true }), true), undefined, "a plain key has no chord");
assert.equal(heldKeyHint(SHORTCUTS.canvasByNumber.map, held({}), true), undefined, "nothing held");
});
test("mod is ⌘ on Apple keyboards and Ctrl elsewhere", () => {
assert.equal(heldKeyHint(SHORTCUTS.app.search, held({ meta: true }), true), "K");
assert.equal(heldKeyHint(SHORTCUTS.app.search, held({ ctrl: true }), true), undefined);
assert.equal(heldKeyHint(SHORTCUTS.app.search, held({ ctrl: true }), false), "K");
assert.equal(heldKeyHint(SHORTCUTS.app.search, held({ meta: true }), false), undefined);
assert.deepEqual(shortcutModifiers(SHORTCUTS.app.search, true), held({ meta: true }));
assert.deepEqual(shortcutModifiers(SHORTCUTS.app.search, false), held({ ctrl: true }));
});
+68 -1
View File
@@ -2,7 +2,7 @@ import assert from "node:assert/strict";
import test from "node:test";
const { tsImport } = await import("tsx/esm/api");
const { HOLD_INITIAL_DELAY_MS, HOLD_FIRST_INTERVAL_MS, HOLD_FLOOR_INTERVAL_MS, holdIntervalMs, holdSchedule } =
const { HOLD_INITIAL_DELAY_MS, HOLD_FIRST_INTERVAL_MS, HOLD_FLOOR_INTERVAL_MS, createKeyHold, glideRate, holdIntervalMs, holdSchedule } =
await tsImport("../../viewer/src/utils/key-hold.ts", import.meta.url);
test("a held paging key waits, then steps sooner and sooner down to a floor", () => {
@@ -16,3 +16,70 @@ test("a held paging key waits, then steps sooner and sooner down to a floor", ()
assert.ok(schedule.at(-1) < 2000, "six held steps fit in two seconds");
assert.ok(HOLD_INITIAL_DELAY_MS > HOLD_FIRST_INTERVAL_MS, "the hold begins slower than it repeats");
});
test("a held key steps on the schedule from its first step, and ends when a step finds nothing", (t) => {
t.mock.timers.enable({ apis: ["setTimeout"] });
const hold = createKeyHold();
let steps = 0;
hold.begin("ArrowRight", () => (steps += 1) < 3);
assert.ok(hold.holding("ArrowRight"));
assert.ok(!hold.holding("ArrowLeft"));
t.mock.timers.tick(HOLD_INITIAL_DELAY_MS - 1);
assert.equal(steps, 0, "nothing before the initial delay");
t.mock.timers.tick(1);
assert.equal(steps, 1, "the second step lands after the initial delay");
t.mock.timers.tick(holdIntervalMs(1));
assert.equal(steps, 2);
t.mock.timers.tick(holdIntervalMs(2));
assert.equal(steps, 3, "the third attempt finds nothing");
assert.ok(!hold.holding("ArrowRight"), "and the hold ends by itself");
t.mock.timers.tick(10_000);
assert.equal(steps, 3, "no further steps");
});
test("ending a hold, or beginning another key, stops the first", (t) => {
t.mock.timers.enable({ apis: ["setTimeout"] });
const hold = createKeyHold();
let right = 0;
let left = 0;
hold.begin("ArrowRight", () => { right += 1; return true; });
t.mock.timers.tick(HOLD_INITIAL_DELAY_MS);
assert.equal(right, 1);
hold.begin("ArrowLeft", () => { left += 1; return true; });
assert.ok(!hold.holding("ArrowRight"));
assert.ok(hold.holding("ArrowLeft"));
// Mock timers run one scheduled round per tick; a hold schedules the next step from each step.
t.mock.timers.tick(HOLD_INITIAL_DELAY_MS);
t.mock.timers.tick(holdIntervalMs(1));
assert.equal(right, 1, "the first key stopped stepping");
assert.equal(left, 2);
hold.end();
assert.ok(!hold.holding("ArrowLeft"));
t.mock.timers.tick(holdIntervalMs(2));
t.mock.timers.tick(1000);
assert.equal(left, 2);
});
test("another key ends a hold, as the OS's own repeat stops; its own repeats and a modifier do not", () => {
const key = (code, key = code, repeat = false) => ({ code, key, repeat });
const hold = createKeyHold();
hold.begin("ArrowDown", () => true);
hold.interrupt(key("ArrowDown", "ArrowDown", true));
hold.interrupt(key("ShiftLeft", "Shift"));
hold.interrupt(key("MetaLeft", "Meta"));
assert.ok(hold.holding("ArrowDown"), "its own repeat and a modifier leave it held");
hold.interrupt(key("Escape"));
assert.ok(!hold.holding("ArrowDown"), "Esc ends it");
hold.begin("ArrowDown", () => true);
hold.interrupt(key("KeyK", "k"));
assert.ok(!hold.holding("ArrowDown"), "so does the K of ⌘K");
hold.end();
});
test("a glide picks up from rest, then eases from the stepped hold's first speed up to its top speed", () => {
assert.equal(glideRate(0), 0, "it starts at rest, where the tap's step ended");
assert.ok(Math.abs(glideRate(80) - 1000 / HOLD_FIRST_INTERVAL_MS) < 0.2, "within a few frames it moves a step per first interval");
for (let at = 10; at <= 1200; at += 10) assert.ok(glideRate(at) >= glideRate(at - 10), `never slows, at ${at}ms`);
assert.equal(glideRate(1000), 1000 / HOLD_FLOOR_INTERVAL_MS, "after a second, a step per floor interval");
assert.equal(glideRate(5000), glideRate(1000), "and no faster");
});
+9 -1
View File
@@ -2,7 +2,7 @@ import assert from "node:assert/strict";
import test from "node:test";
const { tsImport } = await import("tsx/esm/api");
const { mapKeyDirection, mapKeyTarget } = await tsImport("../../viewer/src/utils/map-keyboard.ts", import.meta.url);
const { mapKeyDirection, mapKeyEntry, mapKeyTarget } = await tsImport("../../viewer/src/utils/map-keyboard.ts", import.meta.url);
// A top-to-bottom map: root fans out to a, b, c on one rank; b leads on to d; e is a stray rank with no edges.
// root
@@ -100,3 +100,11 @@ test("a left-to-right map needs no special case: the keys read positions", () =>
assert.equal(mapKeyTarget(rotated, "a", "down"), "b");
assert.equal(mapKeyTarget(rotated, "c", "up"), "b");
});
test("with nothing selected, an arrow enters the map at the edge it moves away from, as Screens' arrows do", () => {
assert.equal(mapKeyEntry(structure, "down"), "root", "down starts at the top");
assert.equal(mapKeyEntry(structure, "up"), "d", "up starts at the bottom; the leftmost of that rank");
assert.equal(mapKeyEntry(structure, "right"), "a", "right starts at the left edge");
assert.equal(mapKeyEntry(structure, "left"), "e", "left starts at the right edge");
assert.equal(mapKeyEntry({ positions: new Map() }, "down"), undefined, "an empty map has no entry");
});
+17 -3
View File
@@ -306,6 +306,8 @@ function ViewerApp() {
const [mapProjectionFitKey, setMapProjectionFitKey] = useState(0);
// A report captured in several appearances shows one at a time; the primary (first captured) is the default.
const [appearanceChoice, setAppearanceChoice] = useState<Appearance | undefined>();
// For the ⇧T shortcut, which steps to the next captured appearance; set once they are known.
const appearanceRef = useRef<{ options: readonly Appearance[]; current: Appearance | undefined }>({ options: [], current: undefined });
const [handoffOpen, setHandoffOpen] = useState(false);
/** Whether this page can hand the report off (a hosted preview); the A key reads it. */
const handoffAvailableRef = useRef(false);
@@ -371,6 +373,10 @@ function ViewerApp() {
const toggleTheme = useCallback(() => {
setThemePreference(current => current === "system" ? "dark" : current === "dark" ? "light" : "system");
}, []);
// The T key flips what is on screen, dark to light and back; only the button returns to Auto.
const flipTheme = useCallback(() => {
setThemePreference(current => (current === "system" ? preferredSystemTheme : current) === "dark" ? "light" : "dark");
}, [preferredSystemTheme]);
const load = useCallback(async (silent = false) => {
void silent;
@@ -994,6 +1000,14 @@ function ViewerApp() {
if (matchesShortcut(event, SHORTCUTS.app.handoff)) {
if (!handoffAvailableRef.current) return;
setHandoffOpen(true);
} else if (matchesShortcut(event, SHORTCUTS.appearance.theme)) {
flipTheme();
} else if (matchesShortcut(event, SHORTCUTS.appearance.app)) {
// Only a report captured in both schemes has another appearance to show.
const { options, current } = appearanceRef.current;
if (options.length < 2) return;
const index = current ? options.indexOf(current) : -1;
setAppearanceChoice(options[(index + 1) % options.length]);
} else if (matchesShortcut(event, SHORTCUTS.app.changes)) {
setChangesOpen((open) => !open);
} else if (matchesShortcut(event, SHORTCUTS.panel.right)) {
@@ -1009,7 +1023,7 @@ function ViewerApp() {
return () => {
window.removeEventListener("keydown", onKeyDown);
};
}, [clearSelectedScreen, navigate, searchOpen, selectCanvas, toggleRightPanel]);
}, [clearSelectedScreen, flipTheme, navigate, searchOpen, selectCanvas, toggleRightPanel]);
// A side-panel row or a deep link is a "go to": the camera fits that screen and the step is
// kept. Screens inventory clicks only select in place; Map clicks also focus the chosen screen. Repeating a selected target refits it without adding history.
@@ -1102,6 +1116,7 @@ function ViewerApp() {
const baseline = builds.find((build) => build.id === route.baseline);
const appearances = useMemo(() => appearanceOptions(payload?.map), [payload]);
const appearance = appearanceChoice && appearances.includes(appearanceChoice) ? appearanceChoice : appearances[0];
appearanceRef.current = { options: appearances, current: appearance };
const appearanceMap = useMemo(() => payload ? filterMapAppearance(payload.map, appearance) : undefined, [appearance, payload]);
const currentMap = useMemo(() => (
appearanceMap && workspace && currentBuild
@@ -1605,7 +1620,6 @@ function ViewerApp() {
) : <CanvasToolbar
canvas={route.canvas}
searchOpen={searchOpen}
compareCount={compareOrder.length}
{...(handoffAction ? { actions: handoffAction } : {})}
onOpenShortcuts={() => setShortcutsOpen(true)}
onSelectCanvas={selectCanvas}
@@ -1614,7 +1628,7 @@ function ViewerApp() {
</CanvasVisibleFrameProvider>
{shortcutsOpen ? (
<ShortcutsDialog
context={{ canvas: route.canvas, review: reviewingInSidebar, hasChanges: compareOrder.length > 0, handoff: Boolean(handoffInput) }}
context={{ canvas: route.canvas, review: reviewingInSidebar, hasChanges: compareOrder.length > 0, handoff: Boolean(handoffInput), appearances: appearances.length > 1 }}
onClose={() => setShortcutsOpen(false)}
/>
) : null}
@@ -3,6 +3,7 @@ import { Fullscreen, LocateFixed } from "lucide-react";
import { runCanvasZoomCommand } from "../../utils/canvas-zoom";
import { useCanvasZoom } from "../../hooks/use-canvas-zoom";
import { formatShortcut, SHORTCUTS } from "../../utils/shortcuts";
import { KeyHint } from "../shared/key-hint";
import { Menu, type MenuItem } from "../shared/menu";
import { Tooltip } from "../shared/tooltip";
import { FullscreenToggleButton, ThemeToggleButton, type ShellActionsProps, type ShellTheme } from "../panels/shell-actions";
@@ -86,6 +87,7 @@ function FitControl() {
disabled={!camera}
onClick={() => runCanvasZoomCommand(camera?.hasSelection() ? "selection" : "fit")}>
<Fullscreen aria-hidden="true" />
<KeyHint shortcut={SHORTCUTS.camera.fit} />
</button>
</Tooltip>
);
@@ -105,6 +107,7 @@ function RecenterControl() {
disabled={!camera}
onClick={() => runCanvasZoomCommand("recenter")}>
<LocateFixed aria-hidden="true" />
<KeyHint shortcut={SHORTCUTS.camera.center} />
</button>
</Tooltip>
);
+4 -7
View File
@@ -2,7 +2,8 @@ import { GitCompareArrows, Keyboard, LayoutGrid, Map, Search } from "lucide-reac
import { type CSSProperties } from "react";
import { Tooltip } from "../shared/tooltip";
import { useCanvasVisibleFrame } from "./visible-frame-provider";
import { formatShortcut, SHORTCUTS } from "../../utils/shortcuts";
import { CANVAS_NUMBER_KEYS, formatShortcut, SHORTCUTS } from "../../utils/shortcuts";
import { KeyHint } from "../shared/key-hint";
import {
CANVAS_DESCRIPTIONS,
CANVAS_LABELS,
@@ -21,9 +22,6 @@ const TOOLBAR_MINIMUM_FRAME_WIDTH = 220;
type CanvasToolbarProps = {
canvas: CanvasView;
searchOpen: boolean;
/** How many changed screens Compare holds, shown as a badge on its button. Compare's own header
steps through them. */
compareCount?: number;
/** Page-wide actions beside Search (Hand off to AI). */
actions?: React.ReactNode;
onSelectCanvas: (canvas: CanvasView) => void;
@@ -60,6 +58,7 @@ export function CanvasToolbar(props: CanvasToolbarProps) {
aria-expanded={props.searchOpen}
onClick={props.onOpenSearch}>
<Search />
<KeyHint shortcut={SHORTCUTS.app.search} />
</button>
</Tooltip>
{props.actions}
@@ -88,9 +87,7 @@ export function CanvasToolbar(props: CanvasToolbarProps) {
onClick={() => props.onSelectCanvas(id)}>
{VIEW_ICONS[id]}
<span className="toolbar-view-label" aria-hidden="true"><span>{CANVAS_LABELS[id]}</span></span>
{id === "compare" && props.compareCount ? (
<span className="toolbar-badge" aria-hidden="true">{props.compareCount}</span>
) : null}
{CANVAS_NUMBER_KEYS ? <KeyHint shortcut={SHORTCUTS.canvasByNumber[id]} /> : null}
</button>
</Tooltip>
);
+60 -3
View File
@@ -3,6 +3,7 @@ import { useReactFlow, useStore } from "@xyflow/react";
import { publishZoom, registerZoomApi, runCanvasZoomCommand } from "../../utils/canvas-zoom";
import { isTyping, matchesShortcut, SHORTCUTS } from "../../utils/shortcuts";
import { useCanvasVisibleFrame } from "./visible-frame-provider";
import { createKeyHold, glideWhileHeld, type KeyHold } from "../../utils/key-hold";
import {
canvasBoundsViewport,
canvasPriorityProjectionBounds,
@@ -15,6 +16,8 @@ import {
} from "./camera";
const DURATION = 160;
/** React Flow's zoomIn/zoomOut step, which a tap of + or − takes. */
const KEY_ZOOM_STEP = 1.2;
const PIXEL_WHEEL_ZOOM_RATE = 0.002;
const LINE_WHEEL_ZOOM_RATE = 0.05;
const PAGE_WHEEL_ZOOM_RATE = 1;
@@ -36,6 +39,12 @@ function canvasOwnsKeyboardEvent(event: KeyboardEvent, canvas: HTMLElement): boo
return focusOwned || canvas.matches(":hover");
}
function plainZoomDirection(event: KeyboardEvent): 1 | -1 | undefined {
if (event.key === "+" || event.key === "=") return 1;
if (event.key === "-" || event.key === "_") return -1;
return undefined;
}
function modifiedZoomCommand(event: KeyboardEvent): "in" | "out" | "100" | undefined {
if (event.code === "Equal" || event.code === "NumpadAdd") return "in";
if (event.code === "Minus" || event.code === "NumpadSubtract") return "out";
@@ -60,6 +69,12 @@ export function ZoomBridge(props: {
fitMaxZoom?: number;
}) {
const { visibleFrame } = useCanvasVisibleFrame();
// Outlives the effect below, which re-runs as the camera moves: a held key must not end just
// because its own zoom step re-registered the listeners.
const holdRef = useRef<KeyHold>(undefined);
holdRef.current ??= createKeyHold();
const hold = holdRef.current;
useEffect(() => () => hold.end(), [hold]);
const {
zoomIn,
zoomOut,
@@ -201,8 +216,37 @@ export function ZoomBridge(props: {
};
registerZoomApi(api);
// A tap of + or − takes one eased step. Held, the OS key repeat is ignored (each repeat
// restarting the easing made holding slower than tapping); once the tap's step has landed the
// camera glides instead, frame by frame about the pane's centre, as zoomIn does, until the key
// is released, the hold is interrupted, or the zoom reaches its limit.
const zoomStep = (direction: 1 | -1): boolean => {
const viewport = getViewport();
const next = Math.min(maxZoom, Math.max(minZoom, viewport.zoom * KEY_ZOOM_STEP ** direction));
if (next === viewport.zoom) return false;
if (direction === 1) void zoomIn({ duration: DURATION });
else void zoomOut({ duration: DURATION });
return true;
};
const zoomGlide = (direction: 1 | -1) => (steps: number): boolean => {
const viewport = getViewport();
const zoom = Math.min(maxZoom, Math.max(minZoom, viewport.zoom * KEY_ZOOM_STEP ** (direction * steps)));
if (zoom === viewport.zoom) return false;
const scale = zoom / viewport.zoom;
const centerX = canvasWidth / 2;
const centerY = canvasHeight / 2;
void setViewport({ zoom, x: centerX - (centerX - viewport.x) * scale, y: centerY - (centerY - viewport.y) * scale });
return true;
};
const onKeyDown = (event: KeyboardEvent) => {
hold.interrupt(event);
// Typing comes first: a held key's repeats belong to a field that took focus mid-hold.
if (isTyping(event.target)) return;
if (event.repeat && hold.holding(event.code)) {
event.preventDefault();
return;
}
// Browser zoom and canvas zoom use the same familiar chord. The pointer/focus boundary
// decides who owns it: canvas-owned events reset its camera; a focused panel or field keeps
@@ -225,10 +269,18 @@ export function ZoomBridge(props: {
event.preventDefault();
return;
}
if (event.key === "+" || event.key === "=") runCanvasZoomCommand("in");
else if (event.key === "-" || event.key === "_") runCanvasZoomCommand("out");
else return;
const direction = plainZoomDirection(event);
if (!direction) return;
event.preventDefault();
onCameraGestureStart.current?.();
if (!zoomStep(direction)) return;
// The hold only tracks the key (released, interrupted, a field or dialog taking over); the
// glide reads it every frame and stops with it.
hold.begin(event.code, () => true);
glideWhileHeld(hold, event.code, DURATION, zoomGlide(direction));
};
const onKeyUp = (event: KeyboardEvent) => {
if (hold.holding(event.code)) hold.end();
};
const onModifierWheel = (event: WheelEvent) => {
@@ -292,9 +344,13 @@ export function ZoomBridge(props: {
};
window.addEventListener("keydown", onKeyDown);
window.addEventListener("keyup", onKeyUp);
window.addEventListener("blur", hold.end);
canvas?.addEventListener("wheel", onModifierWheel, { capture: true, passive: false });
return () => {
window.removeEventListener("keydown", onKeyDown);
window.removeEventListener("keyup", onKeyUp);
window.removeEventListener("blur", hold.end);
canvas?.removeEventListener("wheel", onModifierWheel, { capture: true });
if (wheelFrame.current !== undefined) cancelAnimationFrame(wheelFrame.current);
wheelFrame.current = undefined;
@@ -308,6 +364,7 @@ export function ZoomBridge(props: {
getNodes,
getNodesBounds,
getViewport,
hold,
maxZoom,
minZoom,
props.fitPadding,
@@ -5,6 +5,7 @@ import { StatusGlyph } from "../shared/status-icon";
import { Tooltip } from "../shared/tooltip";
import { DIFF_LABELS, type DiffStatus } from "../../utils/build-diff";
import { formatShortcut, SHORTCUTS } from "../../utils/shortcuts";
import { KeyHint } from "../shared/key-hint";
import { setMeasurementsShown, useMeasurementsShown } from "../../utils/measurements-setting";
/** A screen whose every changed area only moved: how far, per direction, and whether no other finding remains. */
@@ -48,6 +49,7 @@ export function CompareNav(props: {
<StatusGlyph status={props.status} accessibilityOnly={props.accessibilityOnly} label={props.statusLabel ?? DIFF_LABELS[props.status]} />
{/* A route that does not fit loses its start, not the end that names the screen. */}
<code className="compare-nav-route" title={props.title}><bdi>{props.route}</bdi></code>
<KeyHint shortcut={SHORTCUTS.app.changes} />
</button>
</Tooltip>
{props.stepsApart ? null : <CompareSteps {...props} />}
@@ -6,7 +6,7 @@ import type { MapIndex } from "../../utils/model";
import type { ChangedScreen } from "../../utils/changed-screens";
import { groupVisualRegions, layoutShiftSummary, type VisualChange } from "../../utils/visual-diff";
import { formatShortcut, matchesShortcut, SHORTCUTS, shortcutsLive } from "../../utils/shortcuts";
import { HOLD_INITIAL_DELAY_MS, holdIntervalMs } from "../../utils/key-hold";
import { createKeyHold, glideWhileHeld, HOLD_INITIAL_DELAY_MS, type KeyHold } from "../../utils/key-hold";
import { optionalStorage } from "../../utils/embedded-report";
import { usePhoneLayout } from "../../utils/phone-layout";
import { ToggleGroup } from "../shared/toggle-group";
@@ -160,11 +160,12 @@ export function useCompareController(options: CompareControllerOptions) {
};
const flip = () => setFlipSide((side) => (side === "after" ? "before" : "after"));
const keyState = useRef({ previous, next, mode, activeArea, options });
keyState.current = { previous, next, mode, activeArea, options };
const keyState = useRef({ previous, next, mode, activeArea, options, swipePosition });
keyState.current = { previous, next, mode, activeArea, options, swipePosition };
// Stepping to the previous or next changed screen; a held key keeps stepping, accelerating, until
// it is released, the window loses focus, or the list ends. Reads the latest neighbours on each step.
// it is released, the window loses focus, or the end is reached. The Swipe divider is continuous,
// so a tap of [ or ] nudges it one step and a held one glides. Both read the latest state.
const stepScreen = (direction: 1 | -1): boolean => {
const state = keyState.current;
const target = direction === 1 ? state.next : state.previous;
@@ -172,34 +173,38 @@ export function useCompareController(options: CompareControllerOptions) {
state.options.onSelectScreen(target.id);
return true;
};
const hold = useRef<{ code: string; timer: ReturnType<typeof setTimeout> } | undefined>(undefined);
const endHold = () => {
if (!hold.current) return;
clearTimeout(hold.current.timer);
hold.current = undefined;
const moveDivider = (direction: 1 | -1, steps = 1): boolean => {
const state = keyState.current;
if (state.mode !== "swipe") return false;
const position = Math.max(0, Math.min(100, state.swipePosition + direction * SWIPE_STEP * steps));
if (position === state.swipePosition) return false;
state.swipePosition = position;
setSwipePosition(position);
return true;
};
const beginHold = (code: string, direction: 1 | -1) => {
endHold();
let step = 1;
const tick = () => {
if (!stepScreen(direction)) { endHold(); return; }
hold.current = { code, timer: setTimeout(tick, holdIntervalMs(step)) };
step += 1;
};
hold.current = { code, timer: setTimeout(tick, HOLD_INITIAL_DELAY_MS) };
const holdRef = useRef<KeyHold>(undefined);
holdRef.current ??= createKeyHold();
const hold = holdRef.current;
useEffect(() => hold.end, [hold]);
// The hold only tracks the key; the glide reads it every frame and stops with it.
const glideDivider = (code: string, direction: 1 | -1) => {
hold.begin(code, () => true);
glideWhileHeld(hold, code, HOLD_INITIAL_DELAY_MS, (steps) => moveDivider(direction, steps));
};
useEffect(() => endHold, []);
useEffect(() => {
const onKeyDown = (event: KeyboardEvent) => {
hold.interrupt(event);
// The browser's own repeat of the held key is not a step; it must not scroll either.
if (event.repeat && hold.holding(event.code)) { event.preventDefault(); return; }
if (event.defaultPrevented || !shortcutsLive(event)) return;
const state = keyState.current;
const keys = SHORTCUTS.compare;
const stepScreens = state.options.stepScreens !== false;
if (stepScreens && matchesShortcut(event, keys.previousScreen)) {
if (stepScreen(-1)) beginHold(event.code, -1);
if (stepScreen(-1)) hold.begin(event.code, () => stepScreen(-1));
} else if (stepScreens && matchesShortcut(event, keys.nextScreen)) {
if (stepScreen(1)) beginHold(event.code, 1);
if (stepScreen(1)) hold.begin(event.code, () => stepScreen(1));
} else if (matchesShortcut(event, keys.nextArea)) {
stepArea(1);
} else if (matchesShortcut(event, keys.previousArea)) {
@@ -220,10 +225,10 @@ export function useCompareController(options: CompareControllerOptions) {
flip();
} else if (matchesShortcut(event, keys.dividerLeft)) {
if (state.mode !== "swipe") return;
setSwipePosition((value) => Math.max(0, value - SWIPE_STEP));
if (moveDivider(-1)) glideDivider(event.code, -1);
} else if (matchesShortcut(event, keys.dividerRight)) {
if (state.mode !== "swipe") return;
setSwipePosition((value) => Math.min(100, value + SWIPE_STEP));
if (moveDivider(1)) glideDivider(event.code, 1);
} else if (matchesShortcut(event, keys.outlines)) {
toggleOutlines();
} else if (matchesShortcut(event, keys.whatChanged)) {
@@ -234,15 +239,15 @@ export function useCompareController(options: CompareControllerOptions) {
event.preventDefault();
};
const onKeyUp = (event: KeyboardEvent) => {
if (hold.current && event.code === hold.current.code) endHold();
if (hold.holding(event.code)) hold.end();
};
window.addEventListener("keydown", onKeyDown);
window.addEventListener("keyup", onKeyUp);
window.addEventListener("blur", endHold);
window.addEventListener("blur", hold.end);
return () => {
window.removeEventListener("keydown", onKeyDown);
window.removeEventListener("keyup", onKeyUp);
window.removeEventListener("blur", endHold);
window.removeEventListener("blur", hold.end);
};
});
@@ -17,6 +17,8 @@ export type ShortcutContext = {
hasChanges: boolean;
/** The report can be handed off to an agent (a hosted preview). */
handoff?: boolean;
/** The report was captured in both light and dark, so the app's appearance can be switched. */
appearances?: boolean;
};
const COMPARE = SHORTCUTS.compare;
@@ -75,13 +77,15 @@ export function shortcutGroups(context: ShortcutContext): Group[][] {
title: "View",
rows: [
...(context.canvas === "compare" ? [] : [{ label: "Show or hide the inspector", keys: [SHORTCUTS.panel.right] }]),
{ label: "Viewer theme: dark or light", keys: [SHORTCUTS.appearance.theme] },
...(context.appearances ? [{ label: "The app's appearance: light or dark", keys: [SHORTCUTS.appearance.app] }] : []),
{ label: "Show this list", keys: ["?"] },
],
};
const mapGroup: Group = {
title: "Map",
rows: [
{ label: "Walk the map from the selected screen", keys: ["↑", "↓", "←", "→", "H J K L"] },
{ label: "Walk the map, or enter it at an edge", keys: ["↑", "↓", "←", "→", "H J K L"] },
{ label: "Undo or redo moving a card", keys: [SHORTCUTS.edit.undo, SHORTCUTS.edit.redo] },
{ label: "Close the inspector, then deselect", keys: ["Esc"] },
],
+4 -1
View File
@@ -7,6 +7,8 @@ import { isPreviewPath, isReportTargetId, previewReportsUrl, targetQuery } from
import { ScreenshotImage } from "../shared/screenshot-image";
import { artifactUrl } from "../../utils/model";
import { Tooltip } from "../shared/tooltip";
import { KeyHint } from "../shared/key-hint";
import { formatShortcut, SHORTCUTS } from "../../utils/shortcuts";
import { ChangesMenu } from "./changes-menu";
import type { FocusStatus } from "../../utils/navigation";
import type { ExploreMap, MapIndex } from "../../utils/model";
@@ -192,12 +194,13 @@ export function AppPill(props: AppPillProps) {
) : null}
{props.appearance ? (
<>
<Tooltip label="Appearance · the same screens captured in the other scheme" placement="bottom">
<Tooltip label="Appearance · the same screens captured in the other scheme" shortcut={formatShortcut(SHORTCUTS.appearance.app)} placement="bottom">
<button ref={appearanceRef} type="button" className="collapsed-platform" aria-haspopup="menu" aria-expanded={appearanceOpen}
aria-label={`Appearance: ${appearanceLabel(props.appearance.current)}. Show the other appearance`}
onClick={() => setAppearanceOpen(open => !open)}>
{appearanceLabel(props.appearance.current)}
<svg aria-hidden="true" width="8" height="8" viewBox="0 0 8 8"><path d="M1 2.5 4 5.5 7 2.5" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" /></svg>
<KeyHint shortcut={SHORTCUTS.appearance.app} />
</button>
</Tooltip>
<Menu items={appearanceItems} open={appearanceOpen} anchorRef={appearanceRef} ariaLabel="Appearance" onDismiss={() => setAppearanceOpen(false)} />
@@ -1,6 +1,7 @@
import { useEffect, useState } from "react";
import { Maximize, Minimize, Moon, Sun, SunMoon } from "lucide-react";
import { Tooltip } from "../shared/tooltip";
import { formatShortcut, SHORTCUTS } from "../../utils/shortcuts";
import type { ThemePreference } from "../../utils/navigation";
export type ShellTheme = "light" | "dark";
@@ -51,7 +52,7 @@ const THEME_LABELS: Record<ThemePreference, string> = {
export function ThemeToggleButton(props: ShellActionsProps) {
const Icon = props.themePreference === "system" ? SunMoon : props.themePreference === "dark" ? Moon : Sun;
return (
<Tooltip label={THEME_LABELS[props.themePreference]} placement="bottom">
<Tooltip label={THEME_LABELS[props.themePreference]} shortcut={formatShortcut(SHORTCUTS.appearance.theme)} placement="bottom">
<button
type="button"
className={props.className ?? "icon-button"}
+14
View File
@@ -0,0 +1,14 @@
import { heldKeyHint, useHeldModifiers } from "../../utils/held-modifiers";
import type { Shortcut } from "../../utils/shortcuts";
/**
* The key that completes a chord, shown on a button's corner while the chord's modifiers are
* held. Hold ⌃ and the toolbar's sections show 1, 2 and 3; release it and they are gone.
* Nothing renders for a plain key or while nothing is held.
*/
export function KeyHint({ shortcut }: { shortcut: Shortcut }) {
const held = useHeldModifiers();
const key = heldKeyHint(shortcut, held);
if (!key) return null;
return <kbd className="key-hint" aria-hidden="true">{key}</kbd>;
}
+13 -17
View File
@@ -9,7 +9,7 @@ import { screenTree, treeIndex, treeNodeKey, treeScreenOrder, type ScreenTree, t
import type { Appearance } from "../../utils/appearance";
import type { FocusRequest, FocusStatus } from "../../utils/navigation";
import { shortcutsLive } from "../../utils/shortcuts";
import { HOLD_INITIAL_DELAY_MS, holdIntervalMs } from "../../utils/key-hold";
import { createKeyHold } from "../../utils/key-hold";
import { placeholderScreen } from "../../utils/map-frame";
import { ScreenScreenshotCard } from "../canvas/screen-screenshot-card";
import { useCanvasVisibleFrame } from "../canvas/visible-frame-provider";
@@ -393,28 +393,23 @@ export function ScreensView(props: ScreensViewProps) {
pickRef.current(id);
requestAnimationFrame(() => document.getElementById(cardId(id))?.querySelector<HTMLElement>(".screen-screenshot-target")?.focus({ preventScroll: true }));
};
let hold: { code: string; at: string; timer: ReturnType<typeof setTimeout> } | undefined;
const endHold = () => {
if (hold) clearTimeout(hold.timer);
hold = undefined;
};
// A held arrow keeps stepping from the card the last step landed on, not the lagging pick.
const hold = createKeyHold();
const beginHold = (code: string, at: string) => {
endHold();
let step = 1;
const tick = () => {
const id = hold && next(code, hold.at);
if (!hold || !id) { endHold(); return; }
hold.begin(code, () => {
const id = next(code, at);
if (!id) return false;
at = id;
go(id);
hold = { code, at: id, timer: setTimeout(tick, holdIntervalMs(step)) };
step += 1;
};
hold = { code, at, timer: setTimeout(tick, HOLD_INITIAL_DELAY_MS) };
return true;
});
};
const onKeyDown = (event: globalThis.KeyboardEvent) => {
hold.interrupt(event);
const arrow = ["ArrowLeft", "ArrowRight", "ArrowUp", "ArrowDown"].includes(event.code);
if (!arrow && event.key !== "Enter") return;
// The browser's own repeat of a held arrow would scroll the page under the hold.
if (event.repeat && hold?.code === event.code) { event.preventDefault(); return; }
if (event.repeat && hold.holding(event.code)) { event.preventDefault(); return; }
if (event.metaKey || event.ctrlKey || event.altKey || event.shiftKey || event.defaultPrevented || !shortcutsLive(event)) return;
const target = event.target instanceof Element ? event.target : null;
if (!arrow) {
@@ -436,8 +431,9 @@ export function ScreensView(props: ScreensViewProps) {
beginHold(event.code, id);
};
const onKeyUp = (event: globalThis.KeyboardEvent) => {
if (hold && event.code === hold.code) endHold();
if (hold.holding(event.code)) hold.end();
};
const endHold = hold.end;
window.addEventListener("keydown", onKeyDown);
window.addEventListener("keyup", onKeyUp);
window.addEventListener("blur", endHold);
+39 -11
View File
@@ -27,7 +27,8 @@ import type { FocusBehavior, FocusRequest, FocusStatus, MapDirection } from "../
import { focusStatusOf } from "../../utils/changed-screens";
import { displayPathForScreen } from "../../utils/screen-path";
import { shortcutsLive } from "../../utils/shortcuts";
import { mapKeyDirection, mapKeyTarget } from "../../utils/map-keyboard";
import { arrowsOwnedBy, mapKeyDirection, mapKeyEntry, mapKeyTarget, type MapKeyDirection } from "../../utils/map-keyboard";
import { createKeyHold } from "../../utils/key-hold";
const HOVER_CLEAR_DELAY = 180;
const MAP_LAYOUT_REVISION = "flat-v1";
@@ -552,24 +553,51 @@ function ConnectionCanvas(props: MapViewProps) {
if (hoverClearTimer.current !== undefined) window.clearTimeout(hoverClearTimer.current);
applyHover(undefined);
}, [applyHover]);
// With a screen selected, the arrow keys (or h j k l) walk the map: along an edge in the
// layout's flow, across to the neighbour on the same rank otherwise.
// The arrow keys (or h j k l) walk the map from the selected screen: along an edge in the
// layout's flow, across to the neighbour on the same rank otherwise. With nothing selected they
// enter the map at its edge, as on the Screens page. A held key keeps walking.
const { selectedScreenId } = props;
const selectedRef = useRef(selectedScreenId);
selectedRef.current = selectedScreenId;
useEffect(() => {
if (!selectedScreenId) return;
const hold = createKeyHold();
const move = (direction: MapKeyDirection, from: string | undefined): string | undefined => {
const structure = structureRef.current;
if (!structure) return undefined;
return from ? mapKeyTarget(structure, from, direction) : mapKeyEntry(structure, direction);
};
const onKeyDown = (event: KeyboardEvent) => {
if (event.defaultPrevented || !shortcutsLive(event)) return;
hold.interrupt(event);
if (event.repeat && hold.holding(event.code)) { event.preventDefault(); return; }
if (event.defaultPrevented || !shortcutsLive(event) || arrowsOwnedBy(event.target)) return;
const direction = mapKeyDirection(event);
if (!direction) return;
const structure = structureRef.current;
if (!structure) return;
if (!structureRef.current) return;
event.preventDefault();
const target = mapKeyTarget(structure, selectedScreenId, direction);
if (target) selectScreen(target);
let at = move(direction, selectedRef.current);
if (!at) return;
selectScreen(at);
hold.begin(event.code, () => {
const target = move(direction, at);
if (!target) return false;
at = target;
selectScreen(target);
return true;
});
};
const onKeyUp = (event: KeyboardEvent) => {
if (hold.holding(event.code)) hold.end();
};
window.addEventListener("keydown", onKeyDown);
return () => window.removeEventListener("keydown", onKeyDown);
}, [selectScreen, selectedScreenId]);
window.addEventListener("keyup", onKeyUp);
window.addEventListener("blur", hold.end);
return () => {
hold.end();
window.removeEventListener("keydown", onKeyDown);
window.removeEventListener("keyup", onKeyUp);
window.removeEventListener("blur", hold.end);
};
}, [selectScreen]);
const onViewportChange = useCallback((event: CanvasViewportChangeEvent) => {
viewportChangeHandler.current?.(event);
+20 -15
View File
@@ -1064,30 +1064,36 @@ code {
opacity 170ms ease-in-out calc(var(--toolbar-motion) * 0.35),
filter 170ms ease-in-out calc(var(--toolbar-motion) * 0.35);
}
/* Compare's count of changed screens rides on its button's corner. */
.toolbar-button:has(> .toolbar-badge) { position: relative; }
.toolbar-badge {
/* The key that completes a chord, on a button's corner while its modifier is held: hold ⌃ and
the toolbar's sections show 1, 2 and 3. Quiet: a small key in the element colour. */
.toolbar-button:has(> .key-hint), .camera-action-button:has(> .key-hint), .collapsed-platform:has(> .key-hint), .compare-nav-picker:has(> .key-hint) { position: relative; }
.key-hint {
position: absolute;
top: -6px;
right: -6px;
display: flex;
min-width: 18px;
height: 18px;
min-width: 16px;
height: 16px;
align-items: center;
justify-content: center;
padding: 0 5px;
border-radius: 9px;
/* Light theme's deep orange takes white text, as the Modified pill does; dark theme's light
orange takes dark text. */
color: #fff;
background: var(--modified);
box-shadow: 0 0 0 2px var(--surface);
padding: 0 4px;
border-radius: 5px;
color: var(--text);
background: var(--element);
box-shadow: 0 0 0 2px var(--surface), 0 1px 2px rgb(0 0 0 / 0.12);
font: inherit;
font-size: 10px;
font-weight: 700;
font-weight: 600;
line-height: 1;
font-variant-numeric: tabular-nums;
pointer-events: none;
animation: key-hint-in 100ms ease-out;
}
:root[data-theme="dark"] .toolbar-badge { color: #0c0d0e; }
@keyframes key-hint-in {
from { opacity: 0; transform: translateY(2px); }
to { opacity: 1; transform: none; }
}
@media (prefers-reduced-motion: reduce) { .key-hint { animation: none; } }
/* Reduced motion: the bar takes its new width at once; only the names fade, without the blur. */
@media (prefers-reduced-motion: reduce) {
.toolbar-view-label,
@@ -2386,7 +2392,6 @@ html [data-sonner-toaster][data-sonner-theme] {
background: #000;
}
.image-placeholder-reason {
display: block;
max-width: 80%;
+84
View File
@@ -0,0 +1,84 @@
// Which modifier keys are down right now, so a button can show the key that completes a chord
// with them: hold ⌃ and the toolbar's Map, Screens and Compare show 1, 2 and 3. One listener for
// the window; components subscribe and re-render only when the set of held modifiers changes.
import { useSyncExternalStore } from "react";
import { APPLE, isTyping, type Shortcut } from "./shortcuts";
export type HeldModifiers = { shift: boolean; ctrl: boolean; meta: boolean; alt: boolean };
const NONE: HeldModifiers = { shift: false, ctrl: false, meta: false, alt: false };
// The modifiers physically down, and the ones the hints show: none while focus is in a field,
// where a held Shift is for a capital letter, not for a chord. Focus can move by mouse with a
// modifier still down, so the shown set is worked out again on every focus change too.
let physical: HeldModifiers = NONE;
let held: HeldModifiers = NONE;
const listeners = new Set<() => void>();
function same(left: HeldModifiers, right: HeldModifiers): boolean {
return left.shift === right.shift && left.ctrl === right.ctrl && left.meta === right.meta && left.alt === right.alt;
}
function publish() {
const next = isTyping(document.activeElement) ? NONE : physical;
if (same(held, next)) return;
held = same(next, NONE) ? NONE : next;
for (const listener of listeners) listener();
}
function onKey(event: KeyboardEvent) {
physical = { shift: event.shiftKey, ctrl: event.ctrlKey, meta: event.metaKey, alt: event.altKey };
publish();
}
function clear() {
physical = NONE;
publish();
}
function subscribe(listener: () => void) {
if (listeners.size === 0) {
window.addEventListener("keydown", onKey, true);
window.addEventListener("keyup", onKey, true);
// A chord that leaves the page (⌘Tab, a browser shortcut) never sends its key up here.
window.addEventListener("blur", clear);
document.addEventListener("visibilitychange", clear);
document.addEventListener("focusin", publish);
document.addEventListener("focusout", publish);
}
listeners.add(listener);
return () => {
listeners.delete(listener);
if (listeners.size > 0) return;
window.removeEventListener("keydown", onKey, true);
window.removeEventListener("keyup", onKey, true);
window.removeEventListener("blur", clear);
document.removeEventListener("visibilitychange", clear);
document.removeEventListener("focusin", publish);
document.removeEventListener("focusout", publish);
physical = NONE;
held = NONE;
};
}
export function useHeldModifiers(): HeldModifiers {
return useSyncExternalStore(subscribe, () => held, () => NONE);
}
/** The modifiers a shortcut needs, on this keyboard: ⌘ for `mod` on Apple keyboards, Ctrl elsewhere. */
export function shortcutModifiers(shortcut: Shortcut, apple = APPLE): HeldModifiers {
return {
shift: Boolean(shortcut.shift),
ctrl: Boolean(shortcut.ctrl) || (Boolean(shortcut.mod) && !apple),
meta: Boolean(shortcut.mod) && apple,
alt: Boolean(shortcut.alt),
};
}
/**
* The key that completes `shortcut` with exactly the modifiers held, or nothing: a plain key has no
* chord to complete, and a held modifier that is not the shortcut's shows nothing for it.
*/
export function heldKeyHint(shortcut: Shortcut, held: HeldModifiers, apple = APPLE): string | undefined {
if (same(held, NONE)) return undefined;
return same(held, shortcutModifiers(shortcut, apple)) ? shortcut.key : undefined;
}
+94 -1
View File
@@ -2,8 +2,11 @@
* Paging by holding a key. The first step lands on key down; holding past the initial delay keeps
* stepping, each step a little sooner than the last until the floor, the way a held scrollbar arrow
* or a spinner accelerates. The browser's own key repeat is ignored (its rate is a fixed OS setting),
* so the hold is timed here and ends on key up, blur, or the end of the list.
* so the hold is timed here and ends on key up, another key, blur, a field or dialog taking the
* keyboard, or the end of the list.
*/
import { isTyping, modalOpen } from "./shortcuts";
export const HOLD_INITIAL_DELAY_MS = 250;
export const HOLD_FIRST_INTERVAL_MS = 200;
export const HOLD_FLOOR_INTERVAL_MS = 70;
@@ -24,3 +27,93 @@ export function holdSchedule(count: number): number[] {
}
return times;
}
export type KeyHold = {
/**
* Starts holding `code` after its first step already landed. `step` takes the next step and
* says whether there was one; the hold ends by itself when there is not.
*/
begin: (code: string, step: () => boolean) => void;
end: () => void;
/**
* Ends the hold when another key goes down, as the OS's own key repeat stops. A modifier does
* not end it, so ⇧ or ⌘ can join a held key. Call it first in the listener, before any guard.
*/
interrupt: (event: KeyboardEvent) => void;
/** Whether `code` is the key being held. */
holding: (code: string) => boolean;
};
const MODIFIER_KEYS = new Set(["Shift", "Control", "Alt", "Meta"]);
/** Whether the keyboard is still the page's: nothing is being typed into and no dialog is open. */
function keyboardFree(): boolean {
if (typeof document === "undefined") return true;
return !isTyping(document.activeElement) && !modalOpen();
}
// A glide moves at the stepped hold's speeds, in tap steps per second: one step per first
// interval at first, easing up to one per floor interval.
const GLIDE_START_RATE = 1000 / HOLD_FIRST_INTERVAL_MS;
const GLIDE_TOP_RATE = 1000 / HOLD_FLOOR_INTERVAL_MS;
const GLIDE_RAMP_MS = 1000;
/** A glide picks up from rest over this long, so it does not lurch out of the tap's step. */
const GLIDE_PICKUP_MS = 80;
/** How fast a glide moves `elapsed` milliseconds after it began, in tap steps per second. */
export function glideRate(elapsed: number): number {
const ramp = Math.min(1, elapsed / GLIDE_RAMP_MS);
return GLIDE_START_RATE * Math.min(1, elapsed / GLIDE_PICKUP_MS)
+ (GLIDE_TOP_RATE - GLIDE_START_RATE) * ramp * ramp * (3 - 2 * ramp);
}
/**
* For a continuous value (a zoom, a divider) a held key glides instead of stepping: from `delayMs`
* on, `move` is called every frame with how far to go, in tap steps (fractions of one), until the
* hold ends. `move` says whether it moved; at a limit it does not, and the hold ends there.
*/
export function glideWhileHeld(hold: KeyHold, code: string, delayMs: number, move: (steps: number) => boolean): void {
const start = performance.now() + delayMs;
let last = start;
const frame = (now: number) => {
if (!hold.holding(code)) return;
if (now > start) {
const steps = glideRate(now - start) * (now - Math.max(last, start)) / 1000;
last = now;
if (!move(steps)) {
hold.end();
return;
}
}
requestAnimationFrame(frame);
};
requestAnimationFrame(frame);
}
/** One held key at a time, timed on the schedule above. */
export function createKeyHold(): KeyHold {
let current: { code: string; timer: ReturnType<typeof setTimeout> } | undefined;
const end = () => {
if (current) clearTimeout(current.timer);
current = undefined;
};
return {
begin(code, step) {
end();
let count = 1;
const tick = () => {
const next = holdIntervalMs(count);
// A field or a dialog took the keyboard mid-hold: end, rather than step behind it.
if (!current || !keyboardFree() || !step()) { end(); return; }
current = { code, timer: setTimeout(tick, next) };
count += 1;
};
current = { code, timer: setTimeout(tick, HOLD_INITIAL_DELAY_MS) };
},
end,
interrupt(event) {
if (current && !event.repeat && event.code !== current.code && !MODIFIER_KEYS.has(event.key)) end();
},
holding: (code) => current?.code === code,
};
}
+27
View File
@@ -3,6 +3,13 @@ import type { ConnectionGroup } from "./graph-model";
export type MapKeyDirection = "up" | "down" | "left" | "right";
type Point = { x: number; y: number };
const ARROW_WIDGETS = '[role="menu"], [role="menubar"], [role="listbox"], [role="tree"], [role="tablist"], [role="radiogroup"], [role="slider"]';
/** Whether the key's target is a widget whose arrows are its own (a menu item, a list, tabs); the map leaves those keys to it. */
export function arrowsOwnedBy(target: EventTarget | null): boolean {
return target instanceof Element && target.closest(ARROW_WIDGETS) !== null;
}
/** Arrow keys and their Vim twins; anything else is not a map move. */
export function mapKeyDirection(event: Pick<KeyboardEvent, "key" | "altKey" | "ctrlKey" | "metaKey" | "shiftKey">): MapKeyDirection | undefined {
if (event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) return undefined;
@@ -52,3 +59,23 @@ export function mapKeyTarget(
}
return best?.id;
}
/**
* The screen an arrow selects when nothing is: the one at the edge the key moves away from, as
* the Screens page's arrows enter at the first or last card. ↓ takes the topmost screen, ↑ the
* bottom one, → the leftmost, ← the rightmost; ties go to the screen nearest the other axis's start.
*/
export function mapKeyEntry(
structure: { positions: Map<string, Point> },
direction: MapKeyDirection,
): string | undefined {
const vertical = direction === "up" || direction === "down";
const sign = direction === "down" || direction === "right" ? 1 : -1;
let best: { id: string; along: number; across: number } | undefined;
for (const [id, point] of structure.positions) {
const along = sign * (vertical ? point.y : point.x);
const across = vertical ? point.x : point.y;
if (!best || along < best.along || (along === best.along && across < best.across)) best = { id, along, across };
}
return best?.id;
}
+6 -1
View File
@@ -16,7 +16,7 @@ export type Shortcut = {
key: string;
};
const APPLE = typeof navigator !== "undefined"
export const APPLE = typeof navigator !== "undefined"
&& /Mac|iPhone|iPad|iPod/.test(navigator.platform || navigator.userAgent);
/**
@@ -61,6 +61,11 @@ export const SHORTCUTS = {
panel: {
right: plain("KeyI", "I"),
},
/** T is the Viewer's own light or dark theme; ⇧T is the captured app's appearance, in a report that has both. */
appearance: {
theme: plain("KeyT", "T"),
app: shift("KeyT", "T"),
},
/** Canvas edits follow the platform-standard history keys. */
edit: {
undo: mod("KeyZ", "Z"),