Show layout-aware keyboard labels

Display keyboard tutorial labels for the active layout while keeping the existing physical bindings. Fall back to QWERTY/AZERTY labels when layout data is unavailable.

Tested with `npm test` and `npm run build`.
This commit is contained in:
Victor Bonnet
2026-08-29 03:06:26 +00:00
committed by tfrere
parent 013fb39fe4
commit 5d813593e1
4 changed files with 172 additions and 11 deletions
+1
View File
@@ -5,6 +5,7 @@
"type": "module",
"scripts": {
"dev": "vite",
"test": "node --test \"test/**/*.test.js\"",
"build": "vite build",
"preview": "vite preview"
},
+53 -11
View File
@@ -18,6 +18,7 @@ import { INK, ORANGE, MONO } from "../theme.js";
import { ComicButton, ComicTitle, HalftoneRamp, ANTON, CREAM } from "./comic.jsx";
import MenuDuck, { preloadMenuDuck, isMenuDuckReady } from "./MenuDuck.jsx";
import { PreorderButton } from "./Hud.jsx";
import { readLayoutMap, resolveKeycaps } from "./keyboard-layout.js";
const rowIn = keyframes`
from { transform: translateY(12px); opacity: 0; }
@@ -63,13 +64,16 @@ const Kbd = styled("kbd")(({ round }) => ({
// Arcade-style cheat strip pinned at the bottom of the title screen: one
// keycap group + label per move, scannable in a second. The CTA is the
// screen's centre of gravity - players enter first and learn in game.
// Controls bind physical KeyboardEvent.code positions, so letter keycaps
// carry `codes` and get their printed label resolved for the active layout
// (QWERTY fallback where the Keyboard Map API is unavailable).
const SHORTCUTS = {
kb: [
{ caps: ["\u2191\u2190\u2193\u2192"], name: "Move" },
{ caps: ["A", "E"], name: "Kick" },
{ caps: ["R"], name: "Sit" },
{ caps: ["G"], name: "Pick up" },
{ caps: ["C"], name: "Camera" },
{ codes: ["KeyQ", "KeyE"], name: "Kick" },
{ codes: ["KeyR"], name: "Sit" },
{ codes: ["KeyG"], name: "Pick up" },
{ codes: ["KeyC"], name: "Camera" },
{ caps: ["Space"], name: "Reset" },
],
pad: [
@@ -85,8 +89,8 @@ const SHORTCUTS = {
{ caps: ["B"], round: true, name: "Quack" },
],
};
// kb's hint is built at render time from the resolved layout (see kbHint).
const HINTS = {
kb: "ZQSD works too \u00b7 drag to orbit \u00b7 scroll to zoom",
pad: "A ground pick \u00b7 RT quack \u00b7 hold LT wheee \u00b7 R3 chase",
touch: "drag to orbit \u00b7 pinch to zoom",
};
@@ -107,6 +111,33 @@ const VARIANT_ACCENTS = {
const tint = (hex, a) =>
`rgba(${parseInt(hex.slice(1, 3), 16)}, ${parseInt(hex.slice(3, 5), 16)}, ${parseInt(hex.slice(5, 7), 16)}, ${a})`;
const KB_CODES = SHORTCUTS.kb.flatMap((t) => t.codes ?? []);
function useKeycaps(enabled) {
const [keycaps, setKeycaps] = useState(() => resolveKeycaps(KB_CODES, null));
useEffect(() => {
if (!enabled) return;
let cancelled = false;
let latest = 0;
const read = async () => {
const ticket = ++latest;
const map = await readLayoutMap();
// Overlapping reads can settle out of order; only the newest paints.
if (!cancelled && ticket === latest) setKeycaps(resolveKeycaps(KB_CODES, map));
};
read();
const keyboard = navigator.keyboard;
keyboard?.addEventListener?.("layoutchange", read);
return () => {
cancelled = true;
keyboard?.removeEventListener?.("layoutchange", read);
};
}, [enabled]);
return keycaps;
}
function closeMenu() {
useGame.setState({ menuOpen: false });
if (!useGame.getState().entered) useGame.setState({ entered: true });
@@ -126,6 +157,9 @@ export default function TitleMenu() {
const bootFailed = useGame((s) => s.bootFailed);
const [closing, setClosing] = useState(false);
const prevOpen = useRef(menuOpen);
// A plugged-in gamepad wins over the touch tutorial.
const tutorialVariant = padConnected ? "pad" : touchMode ? "touch" : "kb";
const { labels, moveHint } = useKeycaps(tutorialVariant === "kb");
// Touch devices and narrow (mobile-sized) screens skip the 3D stage
// entirely: no duck column, and the GLB is never even downloaded. The
@@ -302,9 +336,16 @@ export default function TitleMenu() {
if (!menuOpen && !closing) return null;
// A plugged-in gamepad wins over the touch tutorial.
const tutorialVariant = padConnected ? "pad" : touchMode ? "touch" : "kb";
const shortcuts = SHORTCUTS[tutorialVariant];
// Letter keycaps resolved for the active layout (QWERTY fallback).
const shortcuts =
tutorialVariant === "kb"
? SHORTCUTS.kb.map((t) =>
t.codes ? { ...t, caps: t.codes.map((code) => labels[code]) } : t,
)
: SHORTCUTS[tutorialVariant];
// The strip's footnote names the letter movement cluster for the active
// layout too ("ZQSD works too" reads wrong on QWERTY and Dvorak).
const kbHint = `${moveHint.replace(/^arrows or /, "")} works too \u00b7 drag to orbit \u00b7 scroll to zoom`;
const ctaLabel = entered ? "Resume" : "Waddle in";
// Blinking key prompt under the CTA; touch has no key to press.
const enterHint = padConnected ? "press A" : touchMode ? null : "press Enter";
@@ -668,8 +709,9 @@ export default function TitleMenu() {
}}
>
<Box sx={{ display: "inline-flex", gap: "0.22rem" }}>
{s.caps.map((c) => (
<Kbd key={c} round={s.round ? 1 : 0}>{c}</Kbd>
{/* Index keys: exotic layouts can print the same glyph twice. */}
{s.caps.map((c, i) => (
<Kbd key={i} round={s.round ? 1 : 0}>{c}</Kbd>
))}
</Box>
<Box
@@ -699,7 +741,7 @@ export default function TitleMenu() {
color: "rgba(255, 255, 255, 0.34)",
}}
>
{HINTS[tutorialVariant]}
{tutorialVariant === "kb" ? kbHint : HINTS[tutorialVariant]}
</Typography>
</Box>
</>
+41
View File
@@ -0,0 +1,41 @@
// Controls use physical KeyboardEvent.code positions; getLayoutMap() provides
// the characters printed on those keys for the active layout.
const FALLBACK_LABELS = Object.freeze({ KeyW: "W/Z", KeyA: "A/Q", KeyQ: "Q/A" });
const MOVEMENT_CODES = ["KeyW", "KeyA", "KeyS", "KeyD"];
const MOVEMENT_FALLBACK_HINT = "arrows or WASD / ZQSD";
function keycap(value) {
if (typeof value !== "string") return null;
const glyph = value.trim();
if ([...glyph].length !== 1 || /[\p{M}\p{C}\p{Z}]/u.test(glyph)) return null;
const upper = glyph.toUpperCase();
return [...upper].length === 1 ? upper : glyph; // "ß" must not become "SS"
}
export function resolveKeycaps(codes, layoutMap) {
const labels = {};
const fromLayout = new Set();
for (const code of new Set([...MOVEMENT_CODES, ...codes])) {
let label = null;
try {
label = keycap(layoutMap?.get?.(code));
} catch {
label = null;
}
if (label) fromLayout.add(code);
labels[code] = label ?? FALLBACK_LABELS[code] ?? code.replace(/^Key/, "");
}
const moveHint = MOVEMENT_CODES.every((code) => fromLayout.has(code))
? `arrows or ${MOVEMENT_CODES.map((code) => labels[code]).join("")}`
: MOVEMENT_FALLBACK_HINT;
return { labels, moveHint };
}
export async function readLayoutMap(nav = globalThis.navigator) {
try {
return (await nav?.keyboard?.getLayoutMap?.()) ?? null;
} catch {
return null;
}
}
+77
View File
@@ -0,0 +1,77 @@
import test from "node:test";
import assert from "node:assert/strict";
import { readLayoutMap, resolveKeycaps } from "../src/ui/keyboard-layout.js";
const AZERTY = new Map(
Object.entries({ KeyW: "z", KeyA: "q", KeyS: "s", KeyD: "d", KeyQ: "a", KeyE: "e" }),
);
const QWERTY = new Map(
Object.entries({ KeyW: "w", KeyA: "a", KeyS: "s", KeyD: "d", KeyQ: "q", KeyE: "e" }),
);
const DVORAK = new Map(
Object.entries({ KeyW: ",", KeyA: "a", KeyS: "o", KeyD: "e", KeyQ: "'", KeyE: "." }),
);
const CODES = ["KeyQ", "KeyE"];
test("resolves caps and the movement hint from the active layout", () => {
assert.deepEqual(resolveKeycaps(CODES, QWERTY), {
labels: { KeyW: "W", KeyA: "A", KeyS: "S", KeyD: "D", KeyQ: "Q", KeyE: "E" },
moveHint: "arrows or WASD",
});
const azerty = resolveKeycaps(CODES, AZERTY);
assert.deepEqual(azerty.labels, {
KeyW: "Z", KeyA: "Q", KeyS: "S", KeyD: "D", KeyQ: "A", KeyE: "E",
});
assert.equal(azerty.moveHint, "arrows or ZQSD");
const dvorak = resolveKeycaps(CODES, DVORAK);
assert.equal(dvorak.labels.KeyQ, "'");
assert.equal(dvorak.moveHint, "arrows or ,AOE");
});
test("falls back to labels naming both layouts without a map", () => {
assert.deepEqual(resolveKeycaps(CODES, null), {
labels: { KeyW: "W/Z", KeyA: "A/Q", KeyS: "S", KeyD: "D", KeyQ: "Q/A", KeyE: "E" },
moveHint: "arrows or WASD / ZQSD",
});
assert.equal(resolveKeycaps(["KeyX"], null).labels.KeyX, "X");
});
test("keeps the inclusive hint when the map misses a movement key", () => {
const partial = new Map([["KeyW", "z"], ["KeyA", "q"], ["KeyS", "s"]]);
const { labels, moveHint } = resolveKeycaps(CODES, partial);
assert.equal(labels.KeyW, "Z");
assert.equal(labels.KeyD, "D");
assert.equal(moveHint, "arrows or WASD / ZQSD");
});
test("rejects layout values that cannot sit on a keycap", () => {
const junk = new Map(
Object.entries({ KeyQ: "", KeyE: " ", KeyW: "Dead", KeyA: "́", KeyS: 7 }),
);
const { labels } = resolveKeycaps(CODES, junk);
assert.deepEqual(labels, {
KeyW: "W/Z", KeyA: "A/Q", KeyS: "S", KeyD: "D", KeyQ: "Q/A", KeyE: "E",
});
});
test("a throwing map cannot break the menu", () => {
const hostile = { get: () => { throw new Error("nope"); } };
assert.equal(resolveKeycaps(CODES, hostile).labels.KeyQ, "Q/A");
});
test("readLayoutMap yields null when the API is absent or refuses", async () => {
assert.equal(await readLayoutMap({}), null);
assert.equal(await readLayoutMap({ keyboard: {} }), null);
const rejects = { keyboard: { getLayoutMap: () => Promise.reject(new Error("blocked")) } };
assert.equal(await readLayoutMap(rejects), null);
const throws = { keyboard: { getLayoutMap: () => { throw new Error("framed"); } } };
assert.equal(await readLayoutMap(throws), null);
});
test("readLayoutMap returns the map where the API is supported", async () => {
const nav = { keyboard: { getLayoutMap: async () => AZERTY } };
assert.equal(await readLayoutMap(nav), AZERTY);
});