@typeonce/ritmo-browser 0.22.0 → 0.24.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1 +1 @@
1
- {"version":3,"file":"InputCapture.d.ts","sourceRoot":"","sources":["../src/InputCapture.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"InputCapture.d.ts","sourceRoot":"","sources":["../src/InputCapture.ts"],"names":[],"mappings":"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"}
@@ -1 +1 @@
1
- {"version":3,"file":"InputCapture.js","sourceRoot":"","sources":["../src/InputCapture.ts"],"names":[],"mappings":"AAsIA;;GAEG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CAQpB,IAA0B,EAC1B,OAAkD,EAClD,EAAE,CACF,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE;IACxB,SAAS,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,QAAoB,CAAC,EAAE;IAC7E,QAAQ,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,OAAO,CAAC,MAAiB,CAAC,EAAE;IAC3E,IAAI,EAAE,CAAC,OAAO,CAAC,IAAI,IAAI,EAAE,CAAS;CACnC,EAAE,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,EAAE,EAAE;IAC7B,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAW,CAAC,CAAA;AAC1D,CAAC,CAAC,CAAA"}
1
+ {"version":3,"file":"InputCapture.js","sourceRoot":"","sources":["../src/InputCapture.ts"],"names":[],"mappings":"AAuIA;;GAEG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CAQpB,IAA0B,EAC1B,OAAkD,EAClD,EAAE,CACF,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE;IACxB,SAAS,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,QAAoB,CAAC,EAAE;IAC7E,QAAQ,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,OAAO,CAAC,MAAiB,CAAC,EAAE;IAC3E,IAAI,EAAE,CAAC,OAAO,CAAC,IAAI,IAAI,EAAE,CAAS;CACnC,EAAE,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,EAAE,EAAE;IAC7B,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAW,CAAC,CAAA;AAC1D,CAAC,CAAC,CAAA"}
@@ -11,19 +11,45 @@
11
11
  * Bind by character (`"w"`) or by physical key (`Keyboard.code("KeyW")`);
12
12
  * see {@link KeyBinding}. A key released while a modifier changed its
13
13
  * character (W pressed, then Option, then W released as "∑") still releases
14
- * its action.
14
+ * its action. Keys that type the same character (both Shift keys, a digit on
15
+ * the row and on the numpad) are one key to a character binding: it is
16
+ * pressed when the first goes down and released when the last comes up.
15
17
  *
16
- * Some combinations never reach the page: browsers reserve shortcuts such as
17
- * Ctrl+W / Cmd+W (close tab), Ctrl+T / Cmd+T, and Cmd+Q, and pages cannot
18
- * prevent them. Avoid Ctrl and Cmd as held modifiers in games.
18
+ * Browser shortcuts are left to the browser: a key pressed with Cmd held, or
19
+ * with Ctrl held, presses no action and is not `preventDefault`-ed, so Ctrl+R
20
+ * still reloads and Ctrl+F still finds while R and F are bound. AltGr reports
21
+ * Ctrl and Alt together and types characters on many layouts, so a key
22
+ * pressed with both is not a shortcut. A game that binds Control or Meta to
23
+ * an action (`"Control"`, `Keyboard.code("ControlLeft")`, ...) keeps every
24
+ * key pressed with them instead, for as long as its bindings hold one; some
25
+ * combinations still never reach the page (Ctrl+W / Cmd+W, Ctrl+T / Cmd+T,
26
+ * Cmd+Q). macOS sends no keyup for a key released while Cmd is down, so
27
+ * Cmd's own release lets go of every held key but the modifiers. A key still
28
+ * down after that, or after a window blur, is pressed again at its next
29
+ * auto-repeat.
19
30
  *
20
- * Keys typed into a form field are left to the field: a key that goes down
21
- * in an `<input>` (any type), `<textarea>`, `<select>`, or contenteditable
22
- * element presses no action and is not `preventDefault`-ed, so a name field
23
- * on the same page as the game receives "wasd" and the player does not move.
24
- * Releases are always processed, so a key held before focus moved into a
25
- * field still releases its action. With `window` as the host this needs no
26
- * setup.
31
+ * Keys the page is using are left to the page: a key that goes down in a
32
+ * form field (`<input>` of any type, `<textarea>`, `<select>`,
33
+ * contenteditable), or inside an open modal dialog (`<dialog>` opened with
34
+ * `showModal()`, or `aria-modal="true"`), or that a listener nearer the
35
+ * target already handled with `preventDefault()` (a menu's arrows, a
36
+ * slider's keys), and Enter, Space, and Tab on a control the player reached
37
+ * by keyboard (Tab to a button, link, tab, or any focusable element: the
38
+ * browser shows it with `:focus-visible`) press no action and are not
39
+ * `preventDefault`-ed. So a name field receives "wasd" and the player does
40
+ * not move, Enter and Space press a focused button, and Escape closes a
41
+ * modal `<dialog>`. Every other key on that focused button is still the
42
+ * game's: movement and hotkeys keep working after the player tabbed to a
43
+ * control. A control the player clicked with the mouse keeps focus but none
44
+ * of the keys: the game keeps playing, and Space does not press it again,
45
+ * with no `tabIndex = -1` or `blur()` in the game. A focused `<canvas>`, or
46
+ * the element passed as the host, is the game, not page UI: when a menu the
47
+ * player used by keyboard closes back into play, focus the canvas
48
+ * (`canvas.tabIndex = -1`, then `canvas.focus()`), or Enter and Space stay
49
+ * with the button the menu handed focus back to. Releases are always
50
+ * processed, so a key held before focus moved still releases its action.
51
+ * With `window` as the host this needs no setup; see {@link KeyEvent} for
52
+ * the exact rule.
27
53
  *
28
54
  * @module Keyboard
29
55
  * @docGroup browser
@@ -81,31 +107,80 @@ import type { ActionState } from "./internal/state.ts";
81
107
  import type { Direction, Vector } from "./internal/vectors.ts";
82
108
  export type { Direction };
83
109
  /**
84
- * The subset of `KeyboardEvent` the module reads. `code` (the physical key)
85
- * and `target` (the element the key was typed into) are optional so simple
86
- * test hosts can omit them; browsers always provide them.
110
+ * The subset of `KeyboardEvent` the module reads. `code` (the physical key),
111
+ * the modifiers, `defaultPrevented`, and `target` (the focused element the
112
+ * key went down in) are optional so simple test hosts can omit them;
113
+ * browsers always provide them. `ctrlKey` and `metaKey` mark a browser
114
+ * shortcut, which {@link actions} leaves to the browser, and `altKey` tells
115
+ * AltGr (Ctrl and Alt together) from Ctrl.
87
116
  *
88
- * A target is a form field, whose key presses {@link actions} and
89
- * {@link presses} leave to it, when its `tagName` is `INPUT` (any type,
90
- * checkboxes and buttons included), `TEXTAREA`, or `SELECT`, or its
91
- * `isContentEditable` is `true`. It is read by shape, not `instanceof`, so
92
- * it works across iframes, and a test host types into a field by passing
93
- * `{ tagName: "INPUT" }` or `{ isContentEditable: true }`.
117
+ * {@link actions} leaves a key to the page when any of these holds:
118
+ *
119
+ * - `defaultPrevented` is `true` because a listener nearer the target (a
120
+ * roving-focus group's arrows, a custom slider, a menu) handled it, not
121
+ * because another `Keyboard.actions` on the same host did;
122
+ * - the target is a form field: its `tagName` is `INPUT` (any type,
123
+ * checkboxes and buttons included), `TEXTAREA`, or `SELECT`, or its
124
+ * `isContentEditable` is `true`;
125
+ * - the target is inside an open modal dialog: `closest` finds a
126
+ * `dialog:modal` (opened with `showModal()`) or an `[aria-modal="true"]`
127
+ * element, however the dialog was opened;
128
+ * - the key is Enter, Space, or Tab (the keys a browser itself acts on for
129
+ * a focused control: press it, move focus on) and the target took focus
130
+ * by keyboard: it matched `:focus-visible` when its `focusin` reached the
131
+ * host, and it is not a `<canvas>` or the host itself (the game's own
132
+ * surface). Any other key on that control is the game's, as a page
133
+ * shortcut still works with a button focused, unless the control handled
134
+ * it (the first rule).
135
+ *
136
+ * {@link presses} offers a key the game asked for, usually from inside a
137
+ * settings dialog, so it skips only a form field's keys and Enter, Space,
138
+ * and Tab on a control reached by keyboard: an open modal dialog and a key a
139
+ * widget handled do not hide a press from it.
140
+ *
141
+ * Focus is judged when it arrives because browsers disagree later: Chromium
142
+ * turns `:focus-visible` on for a clicked button at the first key the player
143
+ * presses, so a check at keydown would hand Space back to a "Mute" button
144
+ * clicked minutes earlier. A focus a script moves (`element.focus()`) counts
145
+ * as by keyboard after the player last used the keyboard in Chromium and
146
+ * Safari, never in Firefox; a dialog's own focus is covered by the modal
147
+ * rule in all three.
148
+ *
149
+ * The target is read by shape, not `instanceof`, so it works across
150
+ * iframes, and a test host types into a field by passing
151
+ * `{ tagName: "INPUT" }` or `{ isContentEditable: true }`, and focuses a
152
+ * control by keyboard by sending `focusin` with a target whose
153
+ * `matches(":focus-visible")` returns `true`.
94
154
  */
95
155
  export interface KeyEvent {
96
156
  readonly key: string;
97
157
  readonly code?: string;
98
158
  readonly repeat: boolean;
159
+ readonly ctrlKey?: boolean;
160
+ readonly metaKey?: boolean;
161
+ readonly altKey?: boolean;
162
+ readonly defaultPrevented?: boolean;
99
163
  readonly target?: object | null;
100
164
  preventDefault(): void;
101
165
  }
102
166
  /**
103
- * The event target the module listens on, usually `window`.
167
+ * The subset of the `focusin` event the module reads: the element that took
168
+ * focus, read by shape like {@link KeyEvent}'s target.
169
+ */
170
+ export interface FocusInEvent {
171
+ readonly target?: object | null;
172
+ }
173
+ /**
174
+ * The event target the module listens on, usually `window`. `focusin` tells
175
+ * which control the player reached by keyboard (see {@link KeyEvent}); a
176
+ * test host that never sends it has no such control.
104
177
  */
105
178
  export interface KeyboardHost {
106
179
  addEventListener(type: "keydown" | "keyup", listener: (event: KeyEvent) => void): void;
180
+ addEventListener(type: "focusin", listener: (event: FocusInEvent) => void): void;
107
181
  addEventListener(type: "blur", listener: () => void): void;
108
182
  removeEventListener(type: "keydown" | "keyup", listener: (event: KeyEvent) => void): void;
183
+ removeEventListener(type: "focusin", listener: (event: FocusInEvent) => void): void;
109
184
  removeEventListener(type: "blur", listener: () => void): void;
110
185
  }
111
186
  /**
@@ -124,7 +199,10 @@ export interface PhysicalKey {
124
199
  * Character bindings follow the keyboard layout and are what a menu should
125
200
  * show. Physical bindings keep a position fixed: WASD stays under the left
126
201
  * hand on AZERTY keyboards, and modifiers cannot change the match (with
127
- * Option held on macOS, W types "∑"; with Shift, 1 types "!").
202
+ * Option held on macOS, W types "∑"; with Shift, 1 types "!"). A character
203
+ * binding matches every key that types it: `"Shift"` is both Shift keys,
204
+ * held while either is down, and `"1"` is the digit row and the numpad;
205
+ * bind `Keyboard.code("ShiftLeft")` for one of them.
128
206
  */
129
207
  export type KeyBinding = string | PhysicalKey;
130
208
  /** The keys of one action: at least one. */
@@ -244,7 +322,10 @@ export interface Actions<B extends Bindings> extends System.Consumes<"snapshot">
244
322
  export interface ActionsOptions {
245
323
  /**
246
324
  * Call `preventDefault()` for bound keys, so arrows and space do not scroll
247
- * the page. Defaults to `true`.
325
+ * the page and a button clicked with the mouse, which keeps focus, is not
326
+ * pressed again by Space or Enter. Defaults to `true`. With `false`, every
327
+ * key the game takes also does what the page does with it (Space presses
328
+ * that clicked button and scrolls); which keys the game takes does not change.
248
329
  */
249
330
  readonly preventDefault?: boolean;
250
331
  }
@@ -255,9 +336,18 @@ export interface ActionsOptions {
255
336
  export declare const idle: <const B extends Bindings>(bindings: B) => Snapshot<B>;
256
337
  /**
257
338
  * Starts tracking bound keys on `host`, usually `window`, until `dispose()`.
258
- * When the window loses focus every held action is released. A key pressed
259
- * in a form field (see {@link KeyEvent}) is left to the field: it
260
- * presses no action and is not `preventDefault`-ed. Each call is
339
+ * When the window loses focus every held action is released. A key the page
340
+ * is using (a form field, an open modal dialog, a key a widget already
341
+ * handled, Enter, Space, and Tab on a control reached by keyboard; see
342
+ * {@link KeyEvent}) is left to
343
+ * the page, and a browser shortcut (a key pressed with Cmd or Ctrl, unless
344
+ * the bindings use Control or Meta) to the browser: it presses no action and
345
+ * is not `preventDefault`-ed. Use it for every key the host reacts to,
346
+ * one-shot keys too (pause on Escape, mute on M: read their `pressed` edge
347
+ * in the snapshot), instead of a `keydown` listener on `window` that calls
348
+ * `preventDefault()` and so takes Enter and Space from a focused button.
349
+ * Binding Tab keeps a keyboard player from moving focus to the page's
350
+ * controls, so a page with controls leaves it unbound. Each call is
261
351
  * its own device: build one per source (one `Controls` merge, one player
262
352
  * of a pool). Use {@link scripted} for tests and headless runs, and
263
353
  * {@link presses} to capture an unbound key on a settings screen.
@@ -274,14 +364,21 @@ export interface KeyPress {
274
364
  export interface Presses extends System.Consumes<"snapshot"> {
275
365
  /** The keys that went down since the previous snapshot, in order, without auto-repeats. */
276
366
  snapshot(): ReadonlyArray<KeyPress>;
277
- /** Removes the event listener. */
367
+ /** Removes the event listeners. */
278
368
  dispose(): void;
279
369
  }
280
370
  /**
281
371
  * Starts collecting every key press on `host`, whatever the bindings, for a
282
372
  * settings screen that waits for the key to bind. Use {@link actions} for
283
373
  * gameplay. It never calls `preventDefault()`, and skips keys pressed in a
284
- * form field (see {@link KeyEvent}).
374
+ * form field, Enter, Space, and Tab on a control reached by keyboard (see
375
+ * {@link KeyEvent}), and browser shortcuts (a key pressed with Cmd or Ctrl),
376
+ * so Ctrl+R on the settings screen binds nothing; Control and Meta pressed
377
+ * alone are offered. Unlike {@link actions} it still offers a key pressed
378
+ * inside an open modal dialog or one a widget handled, since the screen that
379
+ * waits for a key is usually a dialog. For "press any key" on a title or a
380
+ * cutscene, it is the host's listener: it leaves Enter on a button reached
381
+ * by keyboard to the button.
285
382
  *
286
383
  * @example
287
384
  * ```ts
@@ -1 +1 @@
1
- {"version":3,"file":"Keyboard.d.ts","sourceRoot":"","sources":["../src/Keyboard.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"Keyboard.d.ts","sourceRoot":"","sources":["../src/Keyboard.ts"],"names":[],"mappings":"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"}
package/dist/Keyboard.js CHANGED
@@ -7,11 +7,88 @@ const idleState = { held: false, pressed: false, released: false };
7
7
  const editableTags = new Set(["INPUT", "TEXTAREA", "SELECT"]);
8
8
  /** Whether a key event's target is a form field, by the rule on {@link KeyEvent}. */
9
9
  const isEditableTarget = (target) => {
10
- if (target === null || target === undefined)
11
- return false;
12
10
  const { tagName, isContentEditable } = target;
13
11
  return isContentEditable === true || (typeof tagName === "string" && editableTags.has(tagName.toUpperCase()));
14
12
  };
13
+ /** `target.matches(selector)`, false for a target without it or a selector the browser does not know. */
14
+ const matchesSelector = (target, selector) => {
15
+ const { matches } = target;
16
+ if (typeof matches !== "function")
17
+ return false;
18
+ try {
19
+ return matches.call(target, selector) === true;
20
+ }
21
+ catch {
22
+ return false;
23
+ }
24
+ };
25
+ /** Whether `target.closest(selector)` finds an element, false where it cannot ask. */
26
+ const hasAncestor = (target, selector) => {
27
+ const { closest } = target;
28
+ if (typeof closest !== "function")
29
+ return false;
30
+ try {
31
+ const found = closest.call(target, selector);
32
+ return found !== null && found !== undefined;
33
+ }
34
+ catch {
35
+ return false;
36
+ }
37
+ };
38
+ /** Whether the target is inside an open modal dialog. `:modal` is asked of dialogs only, since a fullscreen element can match it too. */
39
+ const isInsideModal = (target) => hasAncestor(target, "[aria-modal=\"true\"]") || hasAncestor(target, "dialog:modal");
40
+ /**
41
+ * The key events a `Keyboard.actions` device prevented: another device on
42
+ * the same host sees them as `defaultPrevented`, and they are still the game's.
43
+ */
44
+ const preventedByKeyboard = new WeakSet();
45
+ /** The keys a browser itself acts on for a focused control: Enter and Space press it, Tab moves focus on. */
46
+ const isControlKey = (event) => event.key === "Enter" || event.key === " " || event.key === "Tab";
47
+ /**
48
+ * Tracks which element took focus by keyboard on `host`, and answers
49
+ * whether a key belongs to the page by the rule on {@link KeyEvent}.
50
+ */
51
+ const pageKeys = (host) => {
52
+ // The element that last took focus while it matched `:focus-visible`, read
53
+ // at `focusin` because Chromium turns it on for a clicked control at the next key.
54
+ let keyboardFocused = null;
55
+ const onFocusIn = (event) => {
56
+ const target = event.target ?? null;
57
+ keyboardFocused = target !== null && matchesSelector(target, ":focus-visible") ? target : null;
58
+ };
59
+ host.addEventListener("focusin", onFocusIn);
60
+ const isGameSurface = (target) => {
61
+ const { tagName } = target;
62
+ return target === host || (typeof tagName === "string" && tagName.toUpperCase() === "CANVAS");
63
+ };
64
+ const isControlPress = (event, target) => target === keyboardFocused && isControlKey(event) && !isGameSurface(target);
65
+ return {
66
+ owns(event) {
67
+ if (event.defaultPrevented === true && !preventedByKeyboard.has(event))
68
+ return true;
69
+ const target = event.target ?? null;
70
+ if (target === null)
71
+ return false;
72
+ return isEditableTarget(target) || isInsideModal(target) || isControlPress(event, target);
73
+ },
74
+ ownsWhileCapturing(event) {
75
+ const target = event.target ?? null;
76
+ return target !== null && (isEditableTarget(target) || isControlPress(event, target));
77
+ },
78
+ dispose() {
79
+ host.removeEventListener("focusin", onFocusIn);
80
+ }
81
+ };
82
+ };
83
+ const modifierKeys = new Set(["Shift", "Control", "Alt", "AltGraph", "Meta"]);
84
+ const modifierCodes = new Set(["ShiftLeft", "ShiftRight", "ControlLeft", "ControlRight", "AltLeft", "AltRight", "MetaLeft", "MetaRight"]);
85
+ /**
86
+ * Whether a key goes down as a browser shortcut: with Cmd, or with Ctrl
87
+ * without Alt (AltGr reports both and types characters), and not a
88
+ * modifier itself.
89
+ */
90
+ const isShortcut = (event) => (event.metaKey === true || (event.ctrlKey === true && event.altKey !== true)) && !modifierKeys.has(event.key);
91
+ const isMeta = (event) => event.key === "Meta" || event.code === "MetaLeft" || event.code === "MetaRight";
15
92
  /**
16
93
  * Binds a vector action to keys for its four directions. The snapshot's
17
94
  * `vectors` reports it with length at most 1: opposite keys cancel and a
@@ -89,11 +166,30 @@ const bindingToken = (binding) => typeof binding === "string" ? keyToken(binding
89
166
  /** How a binding reads in a lint: the character quoted, a physical key by its code. */
90
167
  const bindingLabel = (binding) => typeof binding === "string" ? JSON.stringify(normalize(binding)) : binding.code;
91
168
  const labelsOf = (flat) => [...new Set(Object.values(flat).flatMap((keys) => keys.map(bindingLabel)))];
169
+ const modifierTokens = new Set([...[...modifierKeys].map(keyToken), ...[...modifierCodes].map(codeToken)]);
170
+ /** The tokens of Ctrl and Cmd: a game that binds one keeps the keys pressed with them. */
171
+ const shortcutModifierTokens = [
172
+ keyToken("Control"),
173
+ keyToken("Meta"),
174
+ codeToken("ControlLeft"),
175
+ codeToken("ControlRight"),
176
+ codeToken("MetaLeft"),
177
+ codeToken("MetaRight")
178
+ ];
92
179
  /**
93
180
  * Starts tracking bound keys on `host`, usually `window`, until `dispose()`.
94
- * When the window loses focus every held action is released. A key pressed
95
- * in a form field (see {@link KeyEvent}) is left to the field: it
96
- * presses no action and is not `preventDefault`-ed. Each call is
181
+ * When the window loses focus every held action is released. A key the page
182
+ * is using (a form field, an open modal dialog, a key a widget already
183
+ * handled, Enter, Space, and Tab on a control reached by keyboard; see
184
+ * {@link KeyEvent}) is left to
185
+ * the page, and a browser shortcut (a key pressed with Cmd or Ctrl, unless
186
+ * the bindings use Control or Meta) to the browser: it presses no action and
187
+ * is not `preventDefault`-ed. Use it for every key the host reacts to,
188
+ * one-shot keys too (pause on Escape, mute on M: read their `pressed` edge
189
+ * in the snapshot), instead of a `keydown` listener on `window` that calls
190
+ * `preventDefault()` and so takes Enter and Space from a focused button.
191
+ * Binding Tab keeps a keyboard player from moving focus to the page's
192
+ * controls, so a page with controls leaves it unbound. Each call is
97
193
  * its own device: build one per source (one `Controls` merge, one player
98
194
  * of a pool). Use {@link scripted} for tests and headless runs, and
99
195
  * {@link presses} to capture an unbound key on a settings screen.
@@ -105,6 +201,8 @@ export const actions = (host, initial, options = {}) => {
105
201
  const names = Object.keys(flatten(initial));
106
202
  let bindings = flatten(initial);
107
203
  const actionsByToken = new Map();
204
+ // Off while the bindings use Ctrl or Cmd as a button: then every key pressed with them is the game's.
205
+ let leavesShortcuts = true;
108
206
  const index = () => {
109
207
  actionsByToken.clear();
110
208
  for (const name of names) {
@@ -117,8 +215,10 @@ export const actions = (host, initial, options = {}) => {
117
215
  actionsByToken.set(token, [name]);
118
216
  }
119
217
  }
218
+ leavesShortcuts = !shortcutModifierTokens.some((token) => actionsByToken.has(token));
120
219
  };
121
220
  index();
221
+ const page = pageKeys(host);
122
222
  /**
123
223
  * Each held token and the actions it holds: those bound to it when it went
124
224
  * down that are still bound to it. A token stays here while held even if a
@@ -128,56 +228,106 @@ export const actions = (host, initial, options = {}) => {
128
228
  /**
129
229
  * The character token each physical key produced when it went down, so its
130
230
  * release matches even if a modifier changed the character meanwhile
131
- * (W pressed, Option pressed, W released as "∑").
231
+ * (W pressed, Option pressed, W released as "∑"). It also holds the keys
232
+ * known to be down, form fields and shortcuts included: their repeats
233
+ * press nothing.
132
234
  */
133
235
  const keyTokenByCode = new Map();
236
+ /**
237
+ * The physical keys holding each held character token, so a character two
238
+ * keys type (both Shifts, a digit on the row and on the numpad) stays held
239
+ * until the last of them comes up. A token held through a host that sends
240
+ * no `code` has no entry, and its first release lets go of it.
241
+ */
242
+ const codesByToken = new Map();
134
243
  const pressed = new Set();
135
244
  const released = new Set();
136
- const onKeyDown = (event) => {
137
- // Typed into a form field: the key belongs to the field. Its release is
138
- // still processed by `onKeyUp`.
139
- if (isEditableTarget(event.target))
245
+ const release = (token) => {
246
+ const holding = heldTokens.get(token);
247
+ if (!holding)
140
248
  return;
249
+ heldTokens.delete(token);
250
+ codesByToken.delete(token);
251
+ for (const name of holding)
252
+ released.add(name);
253
+ };
254
+ /** Lets go of `code`'s hold on a character token, releasing it when no other key holds it. */
255
+ const letGo = (token, code) => {
256
+ const codes = codesByToken.get(token);
257
+ if (codes === undefined || !codes.delete(code) || codes.size > 0)
258
+ return;
259
+ release(token);
260
+ };
261
+ const onKeyDown = (event) => {
141
262
  const tokens = [keyToken(event.key)];
263
+ // A repeat of a key known to be down presses nothing; one whose release
264
+ // was missed (a blur, or Cmd on macOS) presses it again. Without `code`,
265
+ // a repeat presses any key that is not held.
266
+ const known = event.code !== undefined && keyTokenByCode.has(event.code);
142
267
  if (event.code !== undefined) {
143
- if (!keyTokenByCode.has(event.code))
268
+ if (!event.repeat || !known) {
269
+ // A new press: the key went up unseen if it was known down, so it no
270
+ // longer holds what it typed then, and its release matches what it types now.
271
+ const before = keyTokenByCode.get(event.code);
272
+ if (before !== undefined && before !== tokens[0])
273
+ letGo(before, event.code);
144
274
  keyTokenByCode.set(event.code, tokens[0]);
275
+ }
145
276
  tokens.push(codeToken(event.code));
146
277
  }
278
+ // A key the page is using belongs to the page; a shortcut belongs to the
279
+ // browser. Their releases are still processed by `onKeyUp`.
280
+ if (page.owns(event) || (leavesShortcuts && isShortcut(event)))
281
+ return;
147
282
  let handled = false;
148
283
  for (const token of tokens) {
149
284
  const bound = actionsByToken.get(token);
150
285
  if (!bound)
151
286
  continue;
152
287
  handled = true;
153
- if (event.repeat || heldTokens.has(token))
288
+ if (event.repeat && known)
289
+ continue;
290
+ // Another key typing the same character joins its hold: one press for both.
291
+ if (event.code !== undefined && token === tokens[0]) {
292
+ const codes = codesByToken.get(token);
293
+ if (codes)
294
+ codes.add(event.code);
295
+ else if (!heldTokens.has(token))
296
+ codesByToken.set(token, new Set([event.code]));
297
+ }
298
+ if (heldTokens.has(token))
154
299
  continue;
155
300
  heldTokens.set(token, new Set(bound));
156
301
  for (const name of bound)
157
302
  pressed.add(name);
158
303
  }
159
- if (handled && preventDefault)
304
+ if (handled && preventDefault) {
160
305
  event.preventDefault();
306
+ preventedByKeyboard.add(event);
307
+ }
161
308
  };
162
- // Releases are processed wherever the key was released, form fields
163
- // included, so a key held before focus moved into a field still releases.
309
+ // Releases are processed wherever the key was released, form fields and
310
+ // focused controls included, so a key held before focus moved still releases.
164
311
  const onKeyUp = (event) => {
165
- const tokens = [keyToken(event.key)];
312
+ const character = event.code === undefined ? keyToken(event.key) : keyTokenByCode.get(event.code) ?? keyToken(event.key);
313
+ if (event.code === undefined || !codesByToken.has(character))
314
+ release(character);
315
+ else
316
+ letGo(character, event.code);
166
317
  if (event.code !== undefined) {
167
- const downAs = keyTokenByCode.get(event.code);
168
318
  keyTokenByCode.delete(event.code);
169
- if (downAs !== undefined)
170
- tokens[0] = downAs;
171
- tokens.push(codeToken(event.code));
172
- }
173
- for (const token of tokens) {
174
- const holding = heldTokens.get(token);
175
- if (!holding)
176
- continue;
177
- heldTokens.delete(token);
178
- for (const name of holding)
179
- released.add(name);
319
+ release(codeToken(event.code));
180
320
  }
321
+ // macOS sends no keyup for a key released while Cmd is down: Cmd's own
322
+ // release lets go of every key but the modifiers, which do get theirs.
323
+ if (!isMeta(event))
324
+ return;
325
+ for (const token of heldTokens.keys())
326
+ if (!modifierTokens.has(token))
327
+ release(token);
328
+ for (const code of keyTokenByCode.keys())
329
+ if (!modifierCodes.has(code))
330
+ keyTokenByCode.delete(code);
181
331
  };
182
332
  const onBlur = () => {
183
333
  for (const holding of heldTokens.values()) {
@@ -185,6 +335,7 @@ export const actions = (host, initial, options = {}) => {
185
335
  released.add(name);
186
336
  }
187
337
  heldTokens.clear();
338
+ codesByToken.clear();
188
339
  keyTokenByCode.clear();
189
340
  };
190
341
  host.addEventListener("keydown", onKeyDown);
@@ -236,6 +387,7 @@ export const actions = (host, initial, options = {}) => {
236
387
  host.removeEventListener("keydown", onKeyDown);
237
388
  host.removeEventListener("keyup", onKeyUp);
238
389
  host.removeEventListener("blur", onBlur);
390
+ page.dispose();
239
391
  }
240
392
  };
241
393
  return live;
@@ -244,7 +396,14 @@ export const actions = (host, initial, options = {}) => {
244
396
  * Starts collecting every key press on `host`, whatever the bindings, for a
245
397
  * settings screen that waits for the key to bind. Use {@link actions} for
246
398
  * gameplay. It never calls `preventDefault()`, and skips keys pressed in a
247
- * form field (see {@link KeyEvent}).
399
+ * form field, Enter, Space, and Tab on a control reached by keyboard (see
400
+ * {@link KeyEvent}), and browser shortcuts (a key pressed with Cmd or Ctrl),
401
+ * so Ctrl+R on the settings screen binds nothing; Control and Meta pressed
402
+ * alone are offered. Unlike {@link actions} it still offers a key pressed
403
+ * inside an open modal dialog or one a widget handled, since the screen that
404
+ * waits for a key is usually a dialog. For "press any key" on a title or a
405
+ * cutscene, it is the host's listener: it leaves Enter on a button reached
406
+ * by keyboard to the button.
248
407
  *
249
408
  * @example
250
409
  * ```ts
@@ -262,8 +421,9 @@ export const actions = (host, initial, options = {}) => {
262
421
  */
263
422
  export const presses = (host) => {
264
423
  let pending = [];
424
+ const page = pageKeys(host);
265
425
  const onKeyDown = (event) => {
266
- if (event.repeat || isEditableTarget(event.target))
426
+ if (event.repeat || page.ownsWhileCapturing(event) || isShortcut(event))
267
427
  return;
268
428
  pending.push({ key: event.key, code: event.code ?? null });
269
429
  };
@@ -276,6 +436,7 @@ export const presses = (host) => {
276
436
  },
277
437
  dispose() {
278
438
  host.removeEventListener("keydown", onKeyDown);
439
+ page.dispose();
279
440
  }
280
441
  };
281
442
  };