Loading files
This file is pinned to the selected release. Download the original to open it in your design tool.
import assert from "node:assert/strict";
import test from "node:test";
import { BOARD_COMMANDS, isBoardCommand, isOverlayTarget, isTypingTarget, resolveBoardKey } from "../boardKeymap.js";
/** A DOM-ish node with just the `closest` the overlay guard calls. */
function node(tagName, { roles = [], isContentEditable = false } = {}) {
const owned = new Set(roles);
return {
tagName,
isContentEditable,
closest(selector) {
return selector
.split(",")
.some((part) => owned.has(part.trim()))
? { tagName: "DIV" }
: null;
},
};
}
/** A keydown with the fields the arbiter reads and nothing else. */
function press(key, options = {}) {
return {
key,
shiftKey: false,
metaKey: false,
ctrlKey: false,
altKey: false,
defaultPrevented: false,
...options,
};
}
// The whole keymap, written out. Every row is one keystroke an engineer will
// actually press; the sweep below proves nothing outside this table fires.
const TABLE = Object.freeze([
{ key: "z", mods: { metaKey: true }, mode: { canUndo: true }, command: "edit.undo" },
{ key: "z", mods: { ctrlKey: true }, mode: { canUndo: true }, command: "edit.undo" },
{ key: "z", mods: { metaKey: true, shiftKey: true }, mode: { canRedo: true }, command: "edit.redo" },
{ key: "y", mods: { ctrlKey: true }, mode: { canRedo: true }, command: "edit.redo" },
{ key: "m", mods: { metaKey: true }, command: "measure.toggle" },
{ key: "m", mods: { ctrlKey: true }, command: "measure.toggle" },
{ key: "PageDown", mods: { ctrlKey: true }, command: "view.fit" },
{ key: "Escape", command: "selection.clear" },
{ key: "c", mods: { shiftKey: true }, command: "filter.clear" },
{ key: "s", mods: { shiftKey: true }, command: "single-layer.cycle" },
{ key: "h", mods: { shiftKey: true }, command: "hud.toggle" },
{ key: "n", mods: { shiftKey: true }, command: "messages.toggle" },
{ key: "1", command: "tab.schematic" },
{ key: "2", command: "tab.pcb" },
{ key: "3", command: "tab.3d" },
{ key: "0", command: "tab.split" },
{ key: "e", command: "edit-mode.toggle" },
{ key: "f", command: "view.fit" },
{ key: "q", command: "units.toggle" },
// Altium's own two: F11 shows/hides the Properties panel, Tab opens
// properties-on-the-fly while placing. Tab only binds when there is a part
// to type coordinates for, so tabbing through the page still works.
{ key: "F11", command: "properties.toggle" },
{ key: "Tab", command: "properties.focus", mode: { canNudge: true } },
{ key: "m", command: "highlight.cycle" },
{ key: "[", command: "mask.decrease" },
{ key: "]", command: "mask.increase" },
{ key: "l", command: "layers.show" },
{ key: "r", command: "regions.toggle" },
// Zoom, on the keys the rail already prints beside its two buttons. All four
// spellings, because `+` is Shift+`=` on most layouts and `_` is Shift+`-`:
// a zoom key that only answers unshifted answers half the keyboards.
// Altium: Ctrl+arrows move the selection by one snap grid unit. Plain arrows
// are Altium's *cursor* keys and stay unbound here (see the resolver).
{ key: "ArrowLeft", mods: { ctrlKey: true }, mode: { canNudge: true }, command: "nudge.left" },
{ key: "ArrowRight", mods: { metaKey: true }, mode: { canNudge: true }, command: "nudge.right" },
{ key: "ArrowUp", mods: { ctrlKey: true }, mode: { canNudge: true }, command: "nudge.up" },
{ key: "ArrowDown", mods: { ctrlKey: true }, mode: { canNudge: true }, command: "nudge.down" },
{ key: "+", mods: { shiftKey: true }, command: "view.zoom-in" },
{ key: "=", command: "view.zoom-in" },
{ key: "-", command: "view.zoom-out" },
{ key: "_", mods: { shiftKey: true }, command: "view.zoom-out" },
]);
test("every published binding resolves to its command, upper and lower case", () => {
for (const row of TABLE) {
assert.equal(resolveBoardKey(press(row.key, row.mods), row.mode || {}), row.command, `${row.key} ${JSON.stringify(row.mods || {})}`);
if (row.key.length === 1) {
const upper = row.key.toUpperCase();
if (upper !== row.key) {
assert.equal(resolveBoardKey(press(upper, row.mods), row.mode || {}), row.command, `${upper} must match ${row.key}`);
}
}
}
});
test("every command in BOARD_COMMANDS is reachable from some keystroke", () => {
const reached = new Set(TABLE.map((row) => row.command));
for (const id of BOARD_COMMANDS) assert.ok(reached.has(id), `${id} has no binding`);
assert.equal(new Set(BOARD_COMMANDS).size, BOARD_COMMANDS.length, "command ids must be unique");
});
// The regression this module exists for: `L` used to toggle the Messages
// drawer, which is neither of Altium's two meanings for the key.
test("L never toggles Messages, in any state", () => {
const modes = [{}, { typing: false }, { canUndo: true }, { canUndo: false, typing: false }];
const mods = [
{},
{ shiftKey: true },
{ ctrlKey: true },
{ metaKey: true },
{ altKey: true },
{ shiftKey: true, metaKey: true },
];
for (const mode of modes) {
for (const modifiers of mods) {
for (const key of ["l", "L"]) {
assert.notEqual(resolveBoardKey(press(key, modifiers), mode), "messages.toggle");
}
}
}
assert.equal(resolveBoardKey(press("l"), {}), "layers.show");
assert.equal(resolveBoardKey(press("n", { shiftKey: true }), {}), "messages.toggle");
});
// The same mistake one key over. ALTIUM-NOTES §3: `Shift+M` shows Altium's
// Board Insight Lens, `Shift+Ctrl+M` auto-zooms it. Spending it on our drawer
// would have moved the misfire rather than fixed it.
test("Shift+M is Altium's Insight Lens and stays unbound", () => {
for (const key of ["m", "M"]) {
assert.equal(resolveBoardKey(press(key, { shiftKey: true }), {}), null, key);
assert.equal(resolveBoardKey(press(key, { shiftKey: true, ctrlKey: true }), {}), "measure.toggle", key);
}
});
// Auto-repeat: a held key is the same event over and over. Only the mask
// steppers mean anything by the second one — a held ⌘Z unwound the whole
// 50-entry history at ~25/sec into a hook with no redo stack.
test("a held key repeats only where repeating is the meaning", () => {
assert.equal(resolveBoardKey(press("z", { metaKey: true, repeat: true }), { canUndo: true }), null);
assert.equal(resolveBoardKey(press("e", { repeat: true }), {}), null);
assert.equal(resolveBoardKey(press("3", { repeat: true }), {}), null);
assert.equal(resolveBoardKey(press("Escape", { repeat: true }), {}), null);
assert.equal(resolveBoardKey(press("[", { repeat: true }), {}), "mask.decrease");
assert.equal(resolveBoardKey(press("]", { repeat: true }), {}), "mask.increase");
// The first press of every binding still lands.
for (const row of TABLE) {
assert.equal(
resolveBoardKey(press(row.key, { ...(row.mods || {}), repeat: false }), row.mode || {}),
row.command,
row.key,
);
}
});
// An overlay owns the keyboard while it is up. The sharp case is Escape:
// Radix dismisses on a capture-phase document listener and never calls
// preventDefault, so without this the sheet closing also dropped the selection
// and disarmed measure.
test("a key pressed inside an overlay never reaches the board", () => {
const inDialog = node("DIV", { roles: ['[role="dialog"]'] });
const inMenu = node("DIV", { roles: ['[role="menu"]'] });
for (const target of [inDialog, inMenu]) {
for (const row of TABLE) {
assert.equal(
resolveBoardKey(press(row.key, { ...(row.mods || {}), target }), row.mode || {}),
null,
`${row.key} inside an overlay`,
);
}
}
// The same key over the board still works — the guard is about where the
// press came from, not about the key.
assert.equal(resolveBoardKey(press("e", { target: node("svg") }), {}), "edit-mode.toggle");
});
test("isOverlayTarget only fires for a real overlay ancestor", () => {
assert.equal(isOverlayTarget(node("DIV", { roles: ['[role="dialog"]'] })), true);
assert.equal(isOverlayTarget(node("DIV", { roles: ['[aria-modal="true"]'] })), true);
assert.equal(isOverlayTarget(node("svg")), false);
// A bare object with no `closest` is what the probe sweep passes.
assert.equal(isOverlayTarget({ tagName: "DIV" }), false);
assert.equal(isOverlayTarget(null), false);
});
test("Ctrl/⌘+Z undoes the board edit, and only when there is one to undo", () => {
assert.equal(resolveBoardKey(press("z", { metaKey: true }), { canUndo: true }), "edit.undo");
assert.equal(resolveBoardKey(press("z", { ctrlKey: true }), { canUndo: true }), "edit.undo");
// Nothing to undo: the key belongs to the browser, not to us.
assert.equal(resolveBoardKey(press("z", { metaKey: true }), { canUndo: false }), null);
assert.equal(resolveBoardKey(press("z", { metaKey: true }), {}), null);
// Plain Z is not undo.
assert.equal(resolveBoardKey(press("z"), { canUndo: true }), null);
});
// Redo is bound on both spellings every application already owns, and gated
// the same way undo is: with nothing to redo the key belongs to the browser,
// because a redo item that did nothing is the same broken promise as the Undo
// this module was written to fix.
test("redo answers ⇧⌘Z and Ctrl+Y, and only when there is something to redo", () => {
for (const event of [
press("z", { metaKey: true, shiftKey: true }),
press("Z", { ctrlKey: true, shiftKey: true }),
press("y", { ctrlKey: true }),
press("Y", { metaKey: true }),
]) {
assert.equal(resolveBoardKey(event, { canRedo: true }), "edit.redo");
assert.equal(resolveBoardKey(event, { canRedo: false, canUndo: true }), null);
}
// Undo and redo never answer the same press.
assert.equal(resolveBoardKey(press("z", { metaKey: true }), { canUndo: true, canRedo: true }), "edit.undo");
assert.equal(
resolveBoardKey(press("z", { metaKey: true, shiftKey: true }), { canUndo: true, canRedo: true }),
"edit.redo",
);
// Held, it does not run away either.
assert.equal(resolveBoardKey(press("y", { ctrlKey: true, repeat: true }), { canRedo: true }), null);
});
test("typing anywhere silences the whole keymap", () => {
for (const row of TABLE) {
assert.equal(resolveBoardKey(press(row.key, row.mods), { ...(row.mode || {}), typing: true }), null);
}
});
test("a key another handler already claimed is left alone", () => {
// Escape dismissing a dropdown must not also clear the user's selection.
assert.equal(resolveBoardKey(press("Escape", { defaultPrevented: true }), {}), null);
assert.equal(resolveBoardKey(press("f", { defaultPrevented: true }), {}), null);
});
test("Alt belongs to the window manager, not to the board", () => {
for (const key of ["f", "l", "e", "q", "1"]) {
assert.equal(resolveBoardKey(press(key, { altKey: true }), { canUndo: true }), null);
}
});
test("a modifier changes the command, it does not stack two of them", () => {
assert.equal(resolveBoardKey(press("m"), {}), "highlight.cycle");
assert.equal(resolveBoardKey(press("n", { shiftKey: true }), {}), "messages.toggle");
assert.equal(resolveBoardKey(press("m", { metaKey: true }), {}), "measure.toggle");
assert.notEqual(resolveBoardKey(press("Escape"), {}), resolveBoardKey(press("c", { shiftKey: true }), {}));
});
// PcbCanvas owns Space (delta origin today, rotation in the spec) on its own
// listener. Two handlers answering one key is the collision this module exists
// to prevent, so the workspace must not claim it.
test("keys another surface owns resolve to null here", () => {
for (const key of [" ", "Insert", "Enter", "Tab", "ArrowUp", "PageUp", "F5", "Delete"]) {
assert.equal(resolveBoardKey(press(key), { canUndo: true }), null, key);
}
});
test("no keystroke in the whole space returns anything the workspace cannot dispatch", () => {
const keys = [
..."abcdefghijklmnopqrstuvwxyz",
..."ABCDEFGHIJKLMNOPQRSTUVWXYZ",
..."0123456789",
..."[]{}()/\\,.;'`-=+*!@#$%^&",
" ",
"Escape",
"Enter",
"Tab",
"Insert",
"Delete",
"Backspace",
"PageUp",
"PageDown",
"Home",
"End",
"ArrowUp",
"ArrowDown",
"ArrowLeft",
"ArrowRight",
"F1",
"F2",
"F5",
"F11",
];
const modifierSets = [];
for (const shiftKey of [false, true]) {
for (const ctrlKey of [false, true]) {
for (const metaKey of [false, true]) {
for (const altKey of [false, true]) {
modifierSets.push({ shiftKey, ctrlKey, metaKey, altKey });
}
}
}
}
let hits = 0;
for (const key of keys) {
for (const modifiers of modifierSets) {
for (const canUndo of [false, true]) {
const command = resolveBoardKey(press(key, modifiers), { canUndo });
if (command === null) continue;
hits += 1;
assert.ok(isBoardCommand(command), `${key} ${JSON.stringify(modifiers)} → unknown command ${command}`);
}
}
}
assert.ok(hits > 0, "the sweep must actually hit bindings");
});
test("a malformed event resolves to nothing rather than throwing", () => {
assert.equal(resolveBoardKey(null, {}), null);
assert.equal(resolveBoardKey({}, {}), null);
assert.equal(resolveBoardKey(press("f")), "view.fit");
});
test("isTypingTarget catches the chat composer, not the canvas", () => {
assert.equal(isTypingTarget({ tagName: "TEXTAREA" }), true);
assert.equal(isTypingTarget({ tagName: "INPUT" }), true);
assert.equal(isTypingTarget({ tagName: "DIV", isContentEditable: true }), true);
assert.equal(isTypingTarget({ tagName: "svg" }), false);
assert.equal(isTypingTarget(null), false);
// A <select> types too: native typeahead picks an option by its first
// character, so `3` on the `Turn by` dropdown must not also switch tabs.
assert.equal(isTypingTarget({ tagName: "SELECT" }), true);
assert.equal(resolveBoardKey(press("3"), { typing: isTypingTarget({ tagName: "SELECT" }) }), null);
assert.equal(resolveBoardKey(press("1"), { typing: isTypingTarget({ tagName: "SELECT" }) }), null);
});
test("arrows are left to the browser when there is nothing to nudge", () => {
// A key that eats a scroll and does nothing is worse than one that scrolls.
for (const key of ["ArrowLeft", "ArrowRight", "ArrowUp", "ArrowDown"]) {
assert.equal(resolveBoardKey(press(key, { ctrlKey: true }), {}), null, key);
assert.equal(resolveBoardKey(press(key, { ctrlKey: true }), { canNudge: false }), null, key);
// And plain arrows are never ours, even with something selected: in Altium
// they move the cursor, and moving a part instead is a silent geometry
// change nobody asked for.
assert.equal(resolveBoardKey(press(key), { canNudge: true }), null, `plain ${key}`);
}
});
test("a held nudge repeats, because ten steps is ten presses otherwise", () => {
assert.equal(
resolveBoardKey(press("ArrowLeft", { ctrlKey: true, repeat: true }), { canNudge: true }),
"nudge.left",
);
// The toggles do not: a held `E` at 25Hz is a flicker, not a gesture.
assert.equal(resolveBoardKey(press("e", { repeat: true }), {}), null);
});
26e259c5cThis file is pinned to the selected release. Download the original to open it in your design tool.