@typeonce/ritmo-browser 0.23.0 → 0.25.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.
- package/CHANGELOG.md +71 -0
- package/README.md +1 -1
- package/dist/Keyboard.d.ts +121 -29
- package/dist/Keyboard.d.ts.map +1 -1
- package/dist/Keyboard.js +159 -17
- package/dist/Keyboard.js.map +1 -1
- package/dist/Touch.d.ts +6 -0
- package/dist/Touch.d.ts.map +1 -1
- package/dist/Touch.js +4 -0
- package/dist/Touch.js.map +1 -1
- package/package.json +2 -2
- package/src/Keyboard.ts +283 -39
- package/src/Touch.ts +11 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,76 @@
|
|
|
1
1
|
# @typeonce/ritmo-browser
|
|
2
2
|
|
|
3
|
+
## 0.25.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- cd6bb2e: **Breaking (a fix to 0.24's modal rule): `Keyboard.actions` leaves every key to the page while a modal dialog is open, wherever focus is.** In 0.24 a key was the page's only when its target was inside the modal. When a redraw deleted the focused button inside an open `<dialog>`, focus fell to `<body>` and the game took the keys again: Z and Space pressed game actions behind the menu, and Escape pressed the game's action and was `preventDefault`-ed, so the dialog did not close.
|
|
8
|
+
|
|
9
|
+
A modal is now open when the key's document holds a `<dialog>` opened with `showModal()`, or an `aria-modal="true"` element that is shown (`checkVisibility({ visibilityProperty: true, opacityProperty: true })`). An `aria-modal` element still in the page but closed (`hidden`, `display: none`, `visibility: hidden`, a closed popover, inside a closed `<dialog>`) leaves the keys with the game, and so does one fading out at `opacity: 0`. `Keyboard.presses` is unchanged.
|
|
10
|
+
|
|
11
|
+
What a game may need to change:
|
|
12
|
+
|
|
13
|
+
- An `aria-modal="true"` element left shown during play now takes every key. Hide it when its menu closes, or remove the attribute:
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
menu.hidden = true // or menu.hidePopover(), or menu.removeAttribute("aria-modal")
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
- A script that hides an `aria-modal` menu on Escape runs before a `window` host hears the key, so the game still gets that Escape. Prevent the key it handled:
|
|
20
|
+
|
|
21
|
+
```ts
|
|
22
|
+
document.addEventListener("keydown", (event) => {
|
|
23
|
+
if (event.key === "Escape" && menu.matches(":popover-open")) {
|
|
24
|
+
event.preventDefault()
|
|
25
|
+
menu.hidePopover()
|
|
26
|
+
}
|
|
27
|
+
})
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
- A game that merged a dialog's Escape with the game's Escape action (both arrived in one frame with focus on `<body>`) now gets only the dialog's.
|
|
31
|
+
|
|
32
|
+
### Patch Changes
|
|
33
|
+
|
|
34
|
+
- 3481d8f: While attached, `Touch.actions` leaves a function on its target that returns the layout at the target's current size, under `Symbol.for("@typeonce/ritmo-browser/Touch.layout")`, so `ritmo-devtools layout` can check the buttons the canvas draws. `dispose()` removes it. Nothing changes for a game.
|
|
35
|
+
- Updated dependencies [ddfca6f]
|
|
36
|
+
- Updated dependencies [cd6bb2e]
|
|
37
|
+
- Updated dependencies [989049f]
|
|
38
|
+
- Updated dependencies [3481d8f]
|
|
39
|
+
- Updated dependencies [bec95ec]
|
|
40
|
+
- @typeonce/ritmo@0.25.0
|
|
41
|
+
|
|
42
|
+
## 0.24.0
|
|
43
|
+
|
|
44
|
+
### Minor Changes
|
|
45
|
+
|
|
46
|
+
- 838358f: **Breaking: `Keyboard.actions` leaves keys the page is using to the page.** Before, only a key typed into a form field was left alone: a bound Enter or Space on a focused `<button>` was `preventDefault`-ed, so a player who reached a menu with Tab could not press it, and Escape did not close a modal `<dialog>`. Now a key presses no action and is not `preventDefault`-ed when any of these holds:
|
|
47
|
+
|
|
48
|
+
- the target is a form field (unchanged);
|
|
49
|
+
- the key is Enter, Space, or Tab and the target took focus by keyboard: it matched `:focus-visible` when focus arrived (Tab to a button, link, `<summary>`, or any element with `tabindex`). Every other key on that control is still the game's, so movement and hotkeys keep working after the player tabbed to a button;
|
|
50
|
+
- the target is inside an open modal dialog (`<dialog>` opened with `showModal()`, or `aria-modal="true"`), however it was opened;
|
|
51
|
+
- a listener nearer the target already called `preventDefault()` on the key (a roving-focus group's arrows, a custom slider, a menu).
|
|
52
|
+
|
|
53
|
+
A button the player clicked with the mouse keeps focus but not the keys: the game keeps playing and Space does not press it again. A focused `<canvas>`, or the element passed as the host, is the game. Releases are processed wherever focus is, as before.
|
|
54
|
+
|
|
55
|
+
`Keyboard.presses` changes less, because the screen that waits for a key is usually a dialog: beyond form fields and browser shortcuts it now skips only Enter, Space, and Tab on a control reached by keyboard, and still offers a key pressed inside a modal dialog or one a widget handled.
|
|
56
|
+
|
|
57
|
+
`KeyboardHost` gains `focusin` listeners (`window` and every element already have them), and `KeyEvent` gains an optional `defaultPrevented`. A test host whose `addEventListener` takes any `type: string` needs no change; a host written with one overload per event adds:
|
|
58
|
+
|
|
59
|
+
```ts
|
|
60
|
+
addEventListener(type: "focusin", listener: (event: Keyboard.FocusInEvent) => void): void
|
|
61
|
+
removeEventListener(type: "focusin", listener: (event: Keyboard.FocusInEvent) => void): void
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
When a menu the player used by keyboard closes back into play, focus the game's canvas (`canvas.tabIndex = -1`, then `canvas.focus()`): a dialog hands focus back to the button that opened it, and the browser then counts that button as reached by keyboard, so Space would press it again.
|
|
65
|
+
|
|
66
|
+
Remove the workarounds this replaces: `tabIndex = -1` on every HUD button and `button.blur()` after each click are no longer needed for the game to keep its keys. A game's own modal menu that it drove through `Keyboard.actions` (Escape or arrows while focus is inside an `aria-modal` element) now gets no actions there: handle those keys on the dialog element, or use a native `<dialog>`, whose Escape closes it. A raw `window` listener that calls `preventDefault()` on a key before the keyboard sees it now keeps that key from the game; bind the key with `Keyboard.actions` instead (`ritmo/use-keyboard-for-game-keys` reports such listeners).
|
|
67
|
+
|
|
68
|
+
### Patch Changes
|
|
69
|
+
|
|
70
|
+
- Updated dependencies [2bbc1ef]
|
|
71
|
+
- Updated dependencies [d2f2543]
|
|
72
|
+
- @typeonce/ritmo@0.24.0
|
|
73
|
+
|
|
3
74
|
## 0.23.0
|
|
4
75
|
|
|
5
76
|
### Minor Changes
|
package/README.md
CHANGED
|
@@ -4,7 +4,7 @@ Browser integrations for ritmo:
|
|
|
4
4
|
|
|
5
5
|
- `BrowserTickSource`: animation frames as a tick source for the core fixed-step loop.
|
|
6
6
|
- `BrowserVisibility`: the Page Visibility API as the `Visibility` of a networked session's `hidden` option, so a hidden tab tells the other peers instead of going silent (see [Hidden tabs](https://github.com/typeonce-dev/ritmo/blob/main/packages/netcode/README.md#hidden-tabs)).
|
|
7
|
-
- Devices, each built with `X.actions(...)` from its host and bindings (a layout for `Touch`) and reporting a snapshot of `actions`, `vectors`, and `used`: `Keyboard` (keys by character or physical key; a key pressed with Ctrl or Cmd is left to the browser as a shortcut unless the game binds Control or Meta), `Gamepad` (standard-mapping button names, sticks, and triggers; a pad without the standard mapping is read by its buttons only, and says so in `standard`), `Pointer` (mouse and pen buttons, chords included, position, wheel, pointer lock), and `Touch` (on-screen controls with named floating sticks, one per vector, and drag-to-aim buttons; a control the game hides is `null` in the layout and lets go of its finger). Keyboard, gamepad, and pointer bindings are rebindable at runtime for a controls settings screen (validate saved ones with `parseRebinding`); every device has scripted timelines for tests, and keyboard, gamepad, and pointer also record them for replays.
|
|
7
|
+
- Devices, each built with `X.actions(...)` from its host and bindings (a layout for `Touch`) and reporting a snapshot of `actions`, `vectors`, and `used`: `Keyboard` (keys by character or physical key; a key pressed with Ctrl or Cmd is left to the browser as a shortcut unless the game binds Control or Meta, and a key the page is using is left to the page: one in a form field, any key while a modal dialog is open, or one already handled by a widget, and Enter, Space, and Tab on a control reached by keyboard, whose other keys stay with the game, while a button clicked with the mouse keeps none), `Gamepad` (standard-mapping button names, sticks, and triggers; a pad without the standard mapping is read by its buttons only, and says so in `standard`), `Pointer` (mouse and pen buttons, chords included, position, wheel, pointer lock), and `Touch` (on-screen controls with named floating sticks, one per vector, and drag-to-aim buttons; a control the game hides is `null` in the layout and lets go of its finger). Keyboard, gamepad, and pointer bindings are rebindable at runtime for a controls settings screen (validate saved ones with `parseRebinding`); every device has scripted timelines for tests, and keyboard, gamepad, and pointer also record them for replays.
|
|
8
8
|
- `Controls`: the game's actions declared once, as buttons and vectors (movement with length at most 1, from keys, d-pad, stick, or touch stick), and the devices merged into one input source; devices used together (keyboard and mouse) are grouped as one. It also holds the types every device shares: `Controls.ActionState` (a button's `held` / `pressed` / `released`) and `Controls.Vector`. `Controls.players` and `Gamepad.pads`: local multiplayer, where players join a slot by pressing a button on any pooled device, every pad on its own.
|
|
9
9
|
- `InputCapture`: the system that drains an input source once per update into a resource. Systems read that resource; a system that calls `snapshot()` itself declares the source with `Game.System.consumeService`. Declare the source service as `InputCapture.SourceOf<typeof device>` (the device's, merge's, or pool's `snapshot()` only), so one descriptor is provided by the live devices in the page, scripted ones in tests, and the recorded or fuzzed input of [`@typeonce/ritmo-devtools`](https://github.com/typeonce-dev/ritmo/blob/main/packages/devtools/README.md) (`Replay`, `Fuzz`); the page keeps the device to rebind and dispose it.
|
|
10
10
|
|
package/dist/Keyboard.d.ts
CHANGED
|
@@ -28,13 +28,29 @@
|
|
|
28
28
|
* down after that, or after a window blur, is pressed again at its next
|
|
29
29
|
* auto-repeat.
|
|
30
30
|
*
|
|
31
|
-
* Keys
|
|
32
|
-
*
|
|
33
|
-
*
|
|
34
|
-
*
|
|
35
|
-
*
|
|
36
|
-
*
|
|
37
|
-
*
|
|
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 while a modal dialog is open (a `<dialog>` opened
|
|
34
|
+
* with `showModal()`, or a shown `aria-modal="true"` element), wherever
|
|
35
|
+
* focus is, or that a listener nearer the target already handled with
|
|
36
|
+
* `preventDefault()` (a menu's arrows, a slider's keys), and Enter, Space,
|
|
37
|
+
* and Tab on a control the player reached
|
|
38
|
+
* by keyboard (Tab to a button, link, tab, or any focusable element: the
|
|
39
|
+
* browser shows it with `:focus-visible`) press no action and are not
|
|
40
|
+
* `preventDefault`-ed. So a name field receives "wasd" and the player does
|
|
41
|
+
* not move, Enter and Space press a focused button, and Escape closes a
|
|
42
|
+
* modal `<dialog>`. Every other key on that focused button is still the
|
|
43
|
+
* game's: movement and hotkeys keep working after the player tabbed to a
|
|
44
|
+
* control. A control the player clicked with the mouse keeps focus but none
|
|
45
|
+
* of the keys: the game keeps playing, and Space does not press it again,
|
|
46
|
+
* with no `tabIndex = -1` or `blur()` in the game. A focused `<canvas>`, or
|
|
47
|
+
* the element passed as the host, is the game, not page UI: when a menu the
|
|
48
|
+
* player used by keyboard closes back into play, focus the canvas
|
|
49
|
+
* (`canvas.tabIndex = -1`, then `canvas.focus()`), or Enter and Space stay
|
|
50
|
+
* with the button the menu handed focus back to. Releases are always
|
|
51
|
+
* processed, so a key held before focus moved still releases its action.
|
|
52
|
+
* With `window` as the host this needs no setup; see {@link KeyEvent} for
|
|
53
|
+
* the exact rule.
|
|
38
54
|
*
|
|
39
55
|
* @module Keyboard
|
|
40
56
|
* @docGroup browser
|
|
@@ -93,18 +109,67 @@ import type { Direction, Vector } from "./internal/vectors.ts";
|
|
|
93
109
|
export type { Direction };
|
|
94
110
|
/**
|
|
95
111
|
* The subset of `KeyboardEvent` the module reads. `code` (the physical key),
|
|
96
|
-
* the modifiers, and `target` (the element the
|
|
97
|
-
* optional so simple test hosts can omit them;
|
|
98
|
-
* `ctrlKey` and `metaKey` mark a browser
|
|
99
|
-
* leaves to the browser, and `altKey` tells
|
|
100
|
-
* from Ctrl.
|
|
112
|
+
* the modifiers, `defaultPrevented`, and `target` (the focused element the
|
|
113
|
+
* key went down in) are optional so simple test hosts can omit them;
|
|
114
|
+
* browsers always provide them. `ctrlKey` and `metaKey` mark a browser
|
|
115
|
+
* shortcut, which {@link actions} leaves to the browser, and `altKey` tells
|
|
116
|
+
* AltGr (Ctrl and Alt together) from Ctrl.
|
|
101
117
|
*
|
|
102
|
-
*
|
|
103
|
-
*
|
|
104
|
-
*
|
|
105
|
-
*
|
|
106
|
-
*
|
|
107
|
-
*
|
|
118
|
+
* {@link actions} leaves a key to the page when any of these holds:
|
|
119
|
+
*
|
|
120
|
+
* - `defaultPrevented` is `true` because a listener nearer the target (a
|
|
121
|
+
* roving-focus group's arrows, a custom slider, a menu) handled it, not
|
|
122
|
+
* because another `Keyboard.actions` on the same host did;
|
|
123
|
+
* - the target is a form field: its `tagName` is `INPUT` (any type,
|
|
124
|
+
* checkboxes and buttons included), `TEXTAREA`, or `SELECT`, or its
|
|
125
|
+
* `isContentEditable` is `true`;
|
|
126
|
+
* - a modal dialog is open, wherever focus is: `closest` from the target
|
|
127
|
+
* finds a `dialog:modal` (opened with `showModal()`) or an
|
|
128
|
+
* `[aria-modal="true"]` element, or the target's document (its
|
|
129
|
+
* `ownerDocument`, or the target itself when it has `querySelector`) holds
|
|
130
|
+
* a `dialog:modal`, or an `[aria-modal="true"]` element that is shown:
|
|
131
|
+
* its `checkVisibility({ visibilityProperty: true, opacityProperty: true })`
|
|
132
|
+
* returns `true`. So a menu keeps its keys after a redraw deleted the
|
|
133
|
+
* focused button and dropped focus to `<body>`, and Escape still closes
|
|
134
|
+
* it. An `aria-modal` element still in the page but closed (`hidden`,
|
|
135
|
+
* `display: none`, `visibility: hidden`, a closed popover, inside a closed
|
|
136
|
+
* `<dialog>`) leaves the keys with the game, and so does one fading out
|
|
137
|
+
* at `opacity: 0`: the player no longer sees the menu. A script that
|
|
138
|
+
* hides an `aria-modal` menu on a key calls `preventDefault()` on it (the
|
|
139
|
+
* first rule): it runs before a `window` host hears the key, and the menu
|
|
140
|
+
* it hid no longer counts. Not seen: a modal inside a shadow root (the
|
|
141
|
+
* target is then the shadow host, and the document query does not look
|
|
142
|
+
* inside it). A modal in another document (an iframe) is modal only
|
|
143
|
+
* there and leaves this host's keys alone;
|
|
144
|
+
* - the key is Enter, Space, or Tab (the keys a browser itself acts on for
|
|
145
|
+
* a focused control: press it, move focus on) and the target took focus
|
|
146
|
+
* by keyboard: it matched `:focus-visible` when its `focusin` reached the
|
|
147
|
+
* host, and it is not a `<canvas>` or the host itself (the game's own
|
|
148
|
+
* surface). Any other key on that control is the game's, as a page
|
|
149
|
+
* shortcut still works with a button focused, unless the control handled
|
|
150
|
+
* it (the first rule).
|
|
151
|
+
*
|
|
152
|
+
* {@link presses} offers a key the game asked for, usually from inside a
|
|
153
|
+
* settings dialog, so it skips only a form field's keys and Enter, Space,
|
|
154
|
+
* and Tab on a control reached by keyboard: an open modal dialog and a key a
|
|
155
|
+
* widget handled do not hide a press from it.
|
|
156
|
+
*
|
|
157
|
+
* Focus is judged when it arrives because browsers disagree later: Chromium
|
|
158
|
+
* turns `:focus-visible` on for a clicked button at the first key the player
|
|
159
|
+
* presses, so a check at keydown would hand Space back to a "Mute" button
|
|
160
|
+
* clicked minutes earlier. A focus a script moves (`element.focus()`) counts
|
|
161
|
+
* as by keyboard after the player last used the keyboard in Chromium and
|
|
162
|
+
* Safari, never in Firefox; a dialog's own focus is covered by the modal
|
|
163
|
+
* rule in all three.
|
|
164
|
+
*
|
|
165
|
+
* The target is read by shape, not `instanceof`, so it works across
|
|
166
|
+
* iframes, and a test host types into a field by passing
|
|
167
|
+
* `{ tagName: "INPUT" }` or `{ isContentEditable: true }`, focuses a
|
|
168
|
+
* control by keyboard by sending `focusin` with a target whose
|
|
169
|
+
* `matches(":focus-visible")` returns `true`, and opens a modal by giving
|
|
170
|
+
* the target an `ownerDocument` whose `querySelector("dialog:modal")`
|
|
171
|
+
* returns an element. A target without those members leaves the key with
|
|
172
|
+
* the game.
|
|
108
173
|
*/
|
|
109
174
|
export interface KeyEvent {
|
|
110
175
|
readonly key: string;
|
|
@@ -113,16 +178,28 @@ export interface KeyEvent {
|
|
|
113
178
|
readonly ctrlKey?: boolean;
|
|
114
179
|
readonly metaKey?: boolean;
|
|
115
180
|
readonly altKey?: boolean;
|
|
181
|
+
readonly defaultPrevented?: boolean;
|
|
116
182
|
readonly target?: object | null;
|
|
117
183
|
preventDefault(): void;
|
|
118
184
|
}
|
|
119
185
|
/**
|
|
120
|
-
* The
|
|
186
|
+
* The subset of the `focusin` event the module reads: the element that took
|
|
187
|
+
* focus, read by shape like {@link KeyEvent}'s target.
|
|
188
|
+
*/
|
|
189
|
+
export interface FocusInEvent {
|
|
190
|
+
readonly target?: object | null;
|
|
191
|
+
}
|
|
192
|
+
/**
|
|
193
|
+
* The event target the module listens on, usually `window`. `focusin` tells
|
|
194
|
+
* which control the player reached by keyboard (see {@link KeyEvent}); a
|
|
195
|
+
* test host that never sends it has no such control.
|
|
121
196
|
*/
|
|
122
197
|
export interface KeyboardHost {
|
|
123
198
|
addEventListener(type: "keydown" | "keyup", listener: (event: KeyEvent) => void): void;
|
|
199
|
+
addEventListener(type: "focusin", listener: (event: FocusInEvent) => void): void;
|
|
124
200
|
addEventListener(type: "blur", listener: () => void): void;
|
|
125
201
|
removeEventListener(type: "keydown" | "keyup", listener: (event: KeyEvent) => void): void;
|
|
202
|
+
removeEventListener(type: "focusin", listener: (event: FocusInEvent) => void): void;
|
|
126
203
|
removeEventListener(type: "blur", listener: () => void): void;
|
|
127
204
|
}
|
|
128
205
|
/**
|
|
@@ -264,7 +341,10 @@ export interface Actions<B extends Bindings> extends System.Consumes<"snapshot">
|
|
|
264
341
|
export interface ActionsOptions {
|
|
265
342
|
/**
|
|
266
343
|
* Call `preventDefault()` for bound keys, so arrows and space do not scroll
|
|
267
|
-
* the page
|
|
344
|
+
* the page and a button clicked with the mouse, which keeps focus, is not
|
|
345
|
+
* pressed again by Space or Enter. Defaults to `true`. With `false`, every
|
|
346
|
+
* key the game takes also does what the page does with it (Space presses
|
|
347
|
+
* that clicked button and scrolls); which keys the game takes does not change.
|
|
268
348
|
*/
|
|
269
349
|
readonly preventDefault?: boolean;
|
|
270
350
|
}
|
|
@@ -275,11 +355,18 @@ export interface ActionsOptions {
|
|
|
275
355
|
export declare const idle: <const B extends Bindings>(bindings: B) => Snapshot<B>;
|
|
276
356
|
/**
|
|
277
357
|
* Starts tracking bound keys on `host`, usually `window`, until `dispose()`.
|
|
278
|
-
* When the window loses focus every held action is released. A key
|
|
279
|
-
*
|
|
280
|
-
*
|
|
281
|
-
*
|
|
282
|
-
*
|
|
358
|
+
* When the window loses focus every held action is released. A key the page
|
|
359
|
+
* is using (a form field, an open modal dialog, a key a widget already
|
|
360
|
+
* handled, Enter, Space, and Tab on a control reached by keyboard; see
|
|
361
|
+
* {@link KeyEvent}) is left to
|
|
362
|
+
* the page, and a browser shortcut (a key pressed with Cmd or Ctrl, unless
|
|
363
|
+
* the bindings use Control or Meta) to the browser: it presses no action and
|
|
364
|
+
* is not `preventDefault`-ed. Use it for every key the host reacts to,
|
|
365
|
+
* one-shot keys too (pause on Escape, mute on M: read their `pressed` edge
|
|
366
|
+
* in the snapshot), instead of a `keydown` listener on `window` that calls
|
|
367
|
+
* `preventDefault()` and so takes Enter and Space from a focused button.
|
|
368
|
+
* Binding Tab keeps a keyboard player from moving focus to the page's
|
|
369
|
+
* controls, so a page with controls leaves it unbound. Each call is
|
|
283
370
|
* its own device: build one per source (one `Controls` merge, one player
|
|
284
371
|
* of a pool). Use {@link scripted} for tests and headless runs, and
|
|
285
372
|
* {@link presses} to capture an unbound key on a settings screen.
|
|
@@ -296,16 +383,21 @@ export interface KeyPress {
|
|
|
296
383
|
export interface Presses extends System.Consumes<"snapshot"> {
|
|
297
384
|
/** The keys that went down since the previous snapshot, in order, without auto-repeats. */
|
|
298
385
|
snapshot(): ReadonlyArray<KeyPress>;
|
|
299
|
-
/** Removes the event
|
|
386
|
+
/** Removes the event listeners. */
|
|
300
387
|
dispose(): void;
|
|
301
388
|
}
|
|
302
389
|
/**
|
|
303
390
|
* Starts collecting every key press on `host`, whatever the bindings, for a
|
|
304
391
|
* settings screen that waits for the key to bind. Use {@link actions} for
|
|
305
392
|
* gameplay. It never calls `preventDefault()`, and skips keys pressed in a
|
|
306
|
-
* form field
|
|
307
|
-
*
|
|
308
|
-
*
|
|
393
|
+
* form field, Enter, Space, and Tab on a control reached by keyboard (see
|
|
394
|
+
* {@link KeyEvent}), and browser shortcuts (a key pressed with Cmd or Ctrl),
|
|
395
|
+
* so Ctrl+R on the settings screen binds nothing; Control and Meta pressed
|
|
396
|
+
* alone are offered. Unlike {@link actions} it still offers a key pressed
|
|
397
|
+
* inside an open modal dialog or one a widget handled, since the screen that
|
|
398
|
+
* waits for a key is usually a dialog. For "press any key" on a title or a
|
|
399
|
+
* cutscene, it is the host's listener: it leaves Enter on a button reached
|
|
400
|
+
* by keyboard to the button.
|
|
309
401
|
*
|
|
310
402
|
* @example
|
|
311
403
|
* ```ts
|
package/dist/Keyboard.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"Keyboard.d.ts","sourceRoot":"","sources":["../src/Keyboard.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"Keyboard.d.ts","sourceRoot":"","sources":["../src/Keyboard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuGG;AACH,OAAO,KAAK,KAAK,MAAM,MAAM,wBAAwB,CAAA;AACrD,OAAO,KAAK,MAAM,MAAM,wBAAwB,CAAA;AAMhD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAA;AAE9D,YAAY,EAAE,SAAS,EAAE,CAAA;AAEzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAA;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B,cAAc,IAAI,IAAI,CAAA;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAChC;AAwKD;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,gBAAgB,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,GAAG,IAAI,CAAA;IACtF,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,IAAI,CAAA;IAChF,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAA;IAC1D,mBAAmB,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,GAAG,IAAI,CAAA;IACzF,mBAAmB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,IAAI,CAAA;IACnF,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAA;CAC9D;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,WAAW,CAAA;AAE7C,4CAA4C;AAC5C,MAAM,MAAM,IAAI,GAAG,SAAS,CAAC,UAAU,EAAE,GAAG,KAAK,CAAC,UAAU,CAAC,CAAC,CAAA;AAE9D;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;IACjB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;IACnB,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAA;CACrB;AAED;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,GAAG,aAAa,CAAC,CAAC,CAAA;AAErE,yDAAyD;AACzD,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,aAAa,GAAG,KAAK,GAAG,CAAC;CAAE,CAAC,MAAM,CAAC,CAAC,GAAG,MAAM,CAAA;AAEzG,qEAAqE;AACrE,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,aAAa,GAAG,CAAC,GAAG,KAAK;CAAE,CAAC,MAAM,CAAC,CAAC,GAAG,MAAM,CAAA;AAEzG;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,MAAM,SAAU;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAA;CAAE,KAAG,aAMnH,CAAA;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,IAAI,GAAI,KAAK,CAAC,IAAI,SAAS,MAAM,QAAQ,IAAI,KAAG,WAAW,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;CAAgB,CAAA;AAEhH;;;GAGG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC,SAAS,QAAQ;IAC1C,QAAQ,CAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,IAAI,WAAW,CAAC,CAAC,CAAC,GAAG,WAAW;KAAE,CAAA;IACtE,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,IAAI,WAAW,CAAC,CAAC,CAAC,GAAG,MAAM;KAAE,CAAA;IACjE,2GAA2G;IAC3G,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CACvB;AAED;;;;GAIG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,QAAQ,IAAI;IAAE,QAAQ,EAAE,MAAM,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,SAAS,aAAa,GAAG,aAAa,GAAG,IAAI;CAAE,CAAA;AAEpI;;;GAGG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,EAAE,CAAC,SAAS,QAAQ,IAAI;IACjD,QAAQ,EAAE,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,GAAG,GAAG,IAAI,GAAG,MAAM,qCAAqC;CACpG,CAAA;AAED;;;;GAIG;AACH,MAAM,WAAW,OAAO,CAAC,CAAC,SAAS,QAAQ,CAAE,SAAQ,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC;IAC9E;;OAEG;IACH,QAAQ,IAAI,QAAQ,CAAC,CAAC,CAAC,CAAA;IACvB;;;;;;;OAOG;IACH,MAAM,CAAC,KAAK,CAAC,CAAC,SAAS,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAAA;IAC7E;;OAEG;IACH,OAAO,IAAI,IAAI,CAAA;CAChB;AAED,mCAAmC;AACnC,MAAM,WAAW,cAAc;IAC7B;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAA;CAClC;AAED;;;GAGG;AACH,eAAO,MAAM,IAAI,GAAI,KAAK,CAAC,CAAC,SAAS,QAAQ,YAAY,CAAC,KAAG,QAAQ,CAAC,CAAC,CACZ,CAAA;AA6D3D;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,OAAO,GAAI,KAAK,CAAC,CAAC,SAAS,QAAQ,QACxC,YAAY,WACT,CAAC,YACD,cAAc,KACtB,OAAO,CAAC,CAAC,CAqLX,CAAA;AAED,iFAAiF;AACjF,MAAM,WAAW,QAAQ;IACvB,0EAA0E;IAC1E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,yGAAyG;IACzG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CAC7B;AAED,oEAAoE;AACpE,MAAM,WAAW,OAAQ,SAAQ,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC;IAC1D,2FAA2F;IAC3F,QAAQ,IAAI,aAAa,CAAC,QAAQ,CAAC,CAAA;IACnC,mCAAmC;IACnC,OAAO,IAAI,IAAI,CAAA;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,OAAO,SAAU,YAAY,KAAG,OAmB5C,CAAA;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,SAAS,QAAQ;IAC/C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAA;IAC/C,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAA;CAClD;AAED;;;GAGG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,QAAQ,IAAI,WAAW,CAAC,CAAC,CAAC,GAAG,GAAG,WAAW,CAAC,CAAC,CAAC,IAAI,SAAS,EAAE,CAAA;AAEhG;;;GAGG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,QAAQ,IAAI,aAAa,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAA;AAE1E;;;GAGG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC,SAAS,QAAQ,CAAE,SAAQ,OAAO,CAAC,CAAC,CAAC;IAC9D,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,MAAM,MAAM,CAAA;CAC9B;AAED;;;;GAIG;AACH,eAAO,MAAM,QAAQ,GAAI,KAAK,CAAC,CAAC,SAAS,QAAQ,YAAY,CAAC,YAAY,QAAQ,CAAC,CAAC,CAAC,KAAG,QAAQ,CAAC,CAAC,CAmDjG,CAAA;AAED;;GAEG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC,SAAS,QAAQ,CAAE,SAAQ,OAAO,CAAC,CAAC,CAAC;IAC/D,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,EAAE,MAAM,QAAQ,CAAC,CAAC,CAAC,CAAA;CACrC;AAED;;;GAGG;AACH,eAAO,MAAM,SAAS,GAAI,CAAC,SAAS,QAAQ,WAAW,OAAO,CAAC,CAAC,CAAC,KAAG,SAAS,CAAC,CAAC,CAyC9E,CAAA;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAA;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GAAI,KAAK,CAAC,CAAC,SAAS,QAAQ,YAC1C,CAAC,QACL,OAAO,KACZ,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,eAAe,CAqC5C,CAAA;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAA;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,cAAc,GAAI,KAAK,CAAC,CAAC,SAAS,QAAQ,YAC3C,CAAC,QACL,OAAO,KACZ,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,gBAAgB,CAuC9C,CAAA"}
|
package/dist/Keyboard.js
CHANGED
|
@@ -7,11 +7,131 @@ 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
|
+
/** The document a key went down in: the target's `ownerDocument`, or the target itself when it is one (it can query). */
|
|
41
|
+
const documentOf = (target) => {
|
|
42
|
+
const { ownerDocument, querySelector } = target;
|
|
43
|
+
if (typeof ownerDocument === "object" && ownerDocument !== null)
|
|
44
|
+
return ownerDocument;
|
|
45
|
+
return typeof querySelector === "function" ? target : null;
|
|
46
|
+
};
|
|
47
|
+
/**
|
|
48
|
+
* Whether an `aria-modal` element is shown. A closed one often stays in the
|
|
49
|
+
* page with its attribute (`hidden`, a closed popover, `display: none`), and
|
|
50
|
+
* one fading out at `opacity: 0` is gone for the player. An element that
|
|
51
|
+
* cannot answer is not shown.
|
|
52
|
+
*/
|
|
53
|
+
const isShown = (element) => {
|
|
54
|
+
if (typeof element !== "object" || element === null)
|
|
55
|
+
return false;
|
|
56
|
+
const { checkVisibility } = element;
|
|
57
|
+
if (typeof checkVisibility !== "function")
|
|
58
|
+
return false;
|
|
59
|
+
return checkVisibility.call(element, { visibilityProperty: true, opacityProperty: true }) === true;
|
|
60
|
+
};
|
|
61
|
+
/** Whether the document holds an open modal dialog, wherever focus is in it. */
|
|
62
|
+
const hasOpenModal = (document) => {
|
|
63
|
+
const { querySelector, querySelectorAll } = document;
|
|
64
|
+
try {
|
|
65
|
+
if (typeof querySelector === "function") {
|
|
66
|
+
const dialog = querySelector.call(document, "dialog:modal");
|
|
67
|
+
if (dialog !== null && dialog !== undefined)
|
|
68
|
+
return true;
|
|
69
|
+
}
|
|
70
|
+
if (typeof querySelectorAll !== "function")
|
|
71
|
+
return false;
|
|
72
|
+
const elements = querySelectorAll.call(document, "[aria-modal=\"true\"]");
|
|
73
|
+
if (typeof elements !== "object" || elements === null || typeof elements.length !== "number")
|
|
74
|
+
return false;
|
|
75
|
+
const list = elements;
|
|
76
|
+
for (let index = 0; index < list.length; index++)
|
|
77
|
+
if (isShown(list[index]))
|
|
78
|
+
return true;
|
|
79
|
+
return false;
|
|
80
|
+
}
|
|
81
|
+
catch {
|
|
82
|
+
return false;
|
|
83
|
+
}
|
|
84
|
+
};
|
|
85
|
+
/** Whether a modal dialog is open for a key with this target, by the rule on {@link KeyEvent}. */
|
|
86
|
+
const isModalOpen = (target) => {
|
|
87
|
+
if (isInsideModal(target))
|
|
88
|
+
return true;
|
|
89
|
+
const document = documentOf(target);
|
|
90
|
+
return document !== null && hasOpenModal(document);
|
|
91
|
+
};
|
|
92
|
+
/**
|
|
93
|
+
* The key events a `Keyboard.actions` device prevented: another device on
|
|
94
|
+
* the same host sees them as `defaultPrevented`, and they are still the game's.
|
|
95
|
+
*/
|
|
96
|
+
const preventedByKeyboard = new WeakSet();
|
|
97
|
+
/** The keys a browser itself acts on for a focused control: Enter and Space press it, Tab moves focus on. */
|
|
98
|
+
const isControlKey = (event) => event.key === "Enter" || event.key === " " || event.key === "Tab";
|
|
99
|
+
/**
|
|
100
|
+
* Tracks which element took focus by keyboard on `host`, and answers
|
|
101
|
+
* whether a key belongs to the page by the rule on {@link KeyEvent}.
|
|
102
|
+
*/
|
|
103
|
+
const pageKeys = (host) => {
|
|
104
|
+
// The element that last took focus while it matched `:focus-visible`, read
|
|
105
|
+
// at `focusin` because Chromium turns it on for a clicked control at the next key.
|
|
106
|
+
let keyboardFocused = null;
|
|
107
|
+
const onFocusIn = (event) => {
|
|
108
|
+
const target = event.target ?? null;
|
|
109
|
+
keyboardFocused = target !== null && matchesSelector(target, ":focus-visible") ? target : null;
|
|
110
|
+
};
|
|
111
|
+
host.addEventListener("focusin", onFocusIn);
|
|
112
|
+
const isGameSurface = (target) => {
|
|
113
|
+
const { tagName } = target;
|
|
114
|
+
return target === host || (typeof tagName === "string" && tagName.toUpperCase() === "CANVAS");
|
|
115
|
+
};
|
|
116
|
+
const isControlPress = (event, target) => target === keyboardFocused && isControlKey(event) && !isGameSurface(target);
|
|
117
|
+
return {
|
|
118
|
+
owns(event) {
|
|
119
|
+
if (event.defaultPrevented === true && !preventedByKeyboard.has(event))
|
|
120
|
+
return true;
|
|
121
|
+
const target = event.target ?? null;
|
|
122
|
+
if (target === null)
|
|
123
|
+
return false;
|
|
124
|
+
return isEditableTarget(target) || isControlPress(event, target) || isModalOpen(target);
|
|
125
|
+
},
|
|
126
|
+
ownsWhileCapturing(event) {
|
|
127
|
+
const target = event.target ?? null;
|
|
128
|
+
return target !== null && (isEditableTarget(target) || isControlPress(event, target));
|
|
129
|
+
},
|
|
130
|
+
dispose() {
|
|
131
|
+
host.removeEventListener("focusin", onFocusIn);
|
|
132
|
+
}
|
|
133
|
+
};
|
|
134
|
+
};
|
|
15
135
|
const modifierKeys = new Set(["Shift", "Control", "Alt", "AltGraph", "Meta"]);
|
|
16
136
|
const modifierCodes = new Set(["ShiftLeft", "ShiftRight", "ControlLeft", "ControlRight", "AltLeft", "AltRight", "MetaLeft", "MetaRight"]);
|
|
17
137
|
/**
|
|
@@ -110,11 +230,18 @@ const shortcutModifierTokens = [
|
|
|
110
230
|
];
|
|
111
231
|
/**
|
|
112
232
|
* Starts tracking bound keys on `host`, usually `window`, until `dispose()`.
|
|
113
|
-
* When the window loses focus every held action is released. A key
|
|
114
|
-
*
|
|
115
|
-
*
|
|
116
|
-
*
|
|
117
|
-
*
|
|
233
|
+
* When the window loses focus every held action is released. A key the page
|
|
234
|
+
* is using (a form field, an open modal dialog, a key a widget already
|
|
235
|
+
* handled, Enter, Space, and Tab on a control reached by keyboard; see
|
|
236
|
+
* {@link KeyEvent}) is left to
|
|
237
|
+
* the page, and a browser shortcut (a key pressed with Cmd or Ctrl, unless
|
|
238
|
+
* the bindings use Control or Meta) to the browser: it presses no action and
|
|
239
|
+
* is not `preventDefault`-ed. Use it for every key the host reacts to,
|
|
240
|
+
* one-shot keys too (pause on Escape, mute on M: read their `pressed` edge
|
|
241
|
+
* in the snapshot), instead of a `keydown` listener on `window` that calls
|
|
242
|
+
* `preventDefault()` and so takes Enter and Space from a focused button.
|
|
243
|
+
* Binding Tab keeps a keyboard player from moving focus to the page's
|
|
244
|
+
* controls, so a page with controls leaves it unbound. Each call is
|
|
118
245
|
* its own device: build one per source (one `Controls` merge, one player
|
|
119
246
|
* of a pool). Use {@link scripted} for tests and headless runs, and
|
|
120
247
|
* {@link presses} to capture an unbound key on a settings screen.
|
|
@@ -143,6 +270,7 @@ export const actions = (host, initial, options = {}) => {
|
|
|
143
270
|
leavesShortcuts = !shortcutModifierTokens.some((token) => actionsByToken.has(token));
|
|
144
271
|
};
|
|
145
272
|
index();
|
|
273
|
+
const page = pageKeys(host);
|
|
146
274
|
/**
|
|
147
275
|
* Each held token and the actions it holds: those bound to it when it went
|
|
148
276
|
* down that are still bound to it. A token stays here while held even if a
|
|
@@ -199,9 +327,13 @@ export const actions = (host, initial, options = {}) => {
|
|
|
199
327
|
}
|
|
200
328
|
tokens.push(codeToken(event.code));
|
|
201
329
|
}
|
|
202
|
-
//
|
|
203
|
-
//
|
|
204
|
-
if (
|
|
330
|
+
// A key bound to no action presses nothing and is not prevented, so the
|
|
331
|
+
// page's rule (which may query the document) is not asked for it.
|
|
332
|
+
if (!tokens.some((token) => actionsByToken.has(token)))
|
|
333
|
+
return;
|
|
334
|
+
// A key the page is using belongs to the page; a shortcut belongs to the
|
|
335
|
+
// browser. Their releases are still processed by `onKeyUp`.
|
|
336
|
+
if (page.owns(event) || (leavesShortcuts && isShortcut(event)))
|
|
205
337
|
return;
|
|
206
338
|
let handled = false;
|
|
207
339
|
for (const token of tokens) {
|
|
@@ -225,11 +357,13 @@ export const actions = (host, initial, options = {}) => {
|
|
|
225
357
|
for (const name of bound)
|
|
226
358
|
pressed.add(name);
|
|
227
359
|
}
|
|
228
|
-
if (handled && preventDefault)
|
|
360
|
+
if (handled && preventDefault) {
|
|
229
361
|
event.preventDefault();
|
|
362
|
+
preventedByKeyboard.add(event);
|
|
363
|
+
}
|
|
230
364
|
};
|
|
231
|
-
// Releases are processed wherever the key was released, form fields
|
|
232
|
-
// included, so a key held before focus moved
|
|
365
|
+
// Releases are processed wherever the key was released, form fields and
|
|
366
|
+
// focused controls included, so a key held before focus moved still releases.
|
|
233
367
|
const onKeyUp = (event) => {
|
|
234
368
|
const character = event.code === undefined ? keyToken(event.key) : keyTokenByCode.get(event.code) ?? keyToken(event.key);
|
|
235
369
|
if (event.code === undefined || !codesByToken.has(character))
|
|
@@ -309,6 +443,7 @@ export const actions = (host, initial, options = {}) => {
|
|
|
309
443
|
host.removeEventListener("keydown", onKeyDown);
|
|
310
444
|
host.removeEventListener("keyup", onKeyUp);
|
|
311
445
|
host.removeEventListener("blur", onBlur);
|
|
446
|
+
page.dispose();
|
|
312
447
|
}
|
|
313
448
|
};
|
|
314
449
|
return live;
|
|
@@ -317,9 +452,14 @@ export const actions = (host, initial, options = {}) => {
|
|
|
317
452
|
* Starts collecting every key press on `host`, whatever the bindings, for a
|
|
318
453
|
* settings screen that waits for the key to bind. Use {@link actions} for
|
|
319
454
|
* gameplay. It never calls `preventDefault()`, and skips keys pressed in a
|
|
320
|
-
* form field
|
|
321
|
-
*
|
|
322
|
-
*
|
|
455
|
+
* form field, Enter, Space, and Tab on a control reached by keyboard (see
|
|
456
|
+
* {@link KeyEvent}), and browser shortcuts (a key pressed with Cmd or Ctrl),
|
|
457
|
+
* so Ctrl+R on the settings screen binds nothing; Control and Meta pressed
|
|
458
|
+
* alone are offered. Unlike {@link actions} it still offers a key pressed
|
|
459
|
+
* inside an open modal dialog or one a widget handled, since the screen that
|
|
460
|
+
* waits for a key is usually a dialog. For "press any key" on a title or a
|
|
461
|
+
* cutscene, it is the host's listener: it leaves Enter on a button reached
|
|
462
|
+
* by keyboard to the button.
|
|
323
463
|
*
|
|
324
464
|
* @example
|
|
325
465
|
* ```ts
|
|
@@ -337,8 +477,9 @@ export const actions = (host, initial, options = {}) => {
|
|
|
337
477
|
*/
|
|
338
478
|
export const presses = (host) => {
|
|
339
479
|
let pending = [];
|
|
480
|
+
const page = pageKeys(host);
|
|
340
481
|
const onKeyDown = (event) => {
|
|
341
|
-
if (event.repeat ||
|
|
482
|
+
if (event.repeat || page.ownsWhileCapturing(event) || isShortcut(event))
|
|
342
483
|
return;
|
|
343
484
|
pending.push({ key: event.key, code: event.code ?? null });
|
|
344
485
|
};
|
|
@@ -351,6 +492,7 @@ export const presses = (host) => {
|
|
|
351
492
|
},
|
|
352
493
|
dispose() {
|
|
353
494
|
host.removeEventListener("keydown", onKeyDown);
|
|
495
|
+
page.dispose();
|
|
354
496
|
}
|
|
355
497
|
};
|
|
356
498
|
};
|