@typeonce/oxlint-plugin-ritmo 0.23.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.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,17 @@
1
1
  # @typeonce/oxlint-plugin-ritmo
2
2
 
3
+ ## 0.24.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 838358f: New rule `ritmo/use-keyboard-for-game-keys`, for every file: reports a `keydown`, `keyup`, or `keypress` listener on `window`, `document`, `document.body`, or `document.documentElement` whose function calls `preventDefault()` on its event. Such a listener takes Enter, Space, and the arrows from a focused button, link, or open dialog, so the page's controls cannot be used by keyboard. Bind the keys with `Keyboard.actions(window, bindings)` and read their `pressed` edges (`Keyboard.presses(window)` for any key), or listen on the UI element the key is for. Turn it on in `.oxlintrc.json`:
8
+
9
+ ```diff
10
+ "rules": {
11
+ + "ritmo/use-keyboard-for-game-keys": "error"
12
+ }
13
+ ```
14
+
3
15
  ## 0.23.0
4
16
 
5
17
  ### Minor Changes
package/README.md CHANGED
@@ -10,7 +10,8 @@ Ritmo's types reject wrong calls, and its devtools lints reject wrong runs. Thes
10
10
  - casts that claim a brand's check without running it;
11
11
  - state values that keep a previous state's fields;
12
12
  - query entities and data kept past their run;
13
- - runtime results that are dropped.
13
+ - runtime results that are dropped;
14
+ - host key listeners that take keys from the page's buttons, links, and dialogs.
14
15
 
15
16
  Every report says what goes wrong and which Ritmo API to use instead.
16
17
 
@@ -31,7 +32,8 @@ Register the plugin and turn the rules on in `.oxlintrc.json`. The simulation ru
31
32
  "ritmo/handle-runtime-result": "error",
32
33
  "ritmo/prefix-descriptor-and-system-names": "error",
33
34
  "ritmo/no-state-spread": "error",
34
- "ritmo/no-kept-query-values": "error"
35
+ "ritmo/no-kept-query-values": "error",
36
+ "ritmo/use-keyboard-for-game-keys": "error"
35
37
  },
36
38
  "overrides": [
37
39
  {
@@ -73,6 +75,7 @@ const started = performance.now()
73
75
  | [`prefix-descriptor-and-system-names`](#ritmoprefix-descriptor-and-system-names) | everywhere | `"Position"`, `Game.System("Move", ...)` | `"Game/Position"` |
74
76
  | [`no-state-spread`](#ritmono-state-spread) | everywhere | `{ ...ground, _tag: "air", vy }` | `data.state.transition(entity, { from, to, data })`, `nextMachines.x.transition({ from, to, data })`, or the new state's fields written out |
75
77
  | [`no-kept-query-values`](#ritmono-kept-query-values) | everywhere | `local.target = queries.x.each()[0]`, `local.slots = queries.x.data` | `entity.id` and `queries.x.get(id)`, or plain values from `queries.x.rows()` |
78
+ | [`use-keyboard-for-game-keys`](#ritmouse-keyboard-for-game-keys) | everywhere | `window.addEventListener("keydown", (e) => { ...; e.preventDefault() })` | `Keyboard.actions(window, bindings)` and its `pressed` edges, or a listener on the UI element |
76
79
 
77
80
  ## Simulation rules
78
81
 
@@ -311,6 +314,29 @@ local.rows = queries.targets.rows() // plain values, safe to keep
311
314
 
312
315
  Ids (`entity.id`, `.map((entity) => entity.id)`), values read from `data`, and rows are not reported, nor are variables of the run itself (`let best` in the system's body). An entity handed to a service (`services.cache.remember(entity)`) is not judged: the rule cannot see what the service keeps.
313
316
 
317
+ ### `ritmo/use-keyboard-for-game-keys`
318
+
319
+ A `keydown` listener on the whole page runs for every key, whatever has focus, so one that calls `preventDefault()` for Enter, Space, or the arrows also stops them on a focused button, link, tab, or open dialog: a player who reaches a menu by keyboard cannot press it, and Escape does not close a modal `<dialog>`. Games then hide it with `tabIndex = -1` on every button or `blur()` after each click. [`Keyboard.actions`](https://github.com/typeonce-dev/ritmo/blob/main/packages/browser/README.md) leaves keys the page is using to the page (a form field, a control reached by keyboard, an open modal dialog, a key a widget already handled) and keeps them when a control only kept focus after a click.
320
+
321
+ ```ts
322
+ window.addEventListener("keydown", (event) => { // reported
323
+ if (event.key === "Escape") togglePause()
324
+ else if (event.key === " ") jump()
325
+ else return
326
+ event.preventDefault()
327
+ })
328
+
329
+ // instead
330
+ const keys = Keyboard.actions(window, { pause: ["Escape"], jump: [" "] })
331
+ // once per frame, or through InputCapture / Controls:
332
+ const snapshot = keys.snapshot()
333
+ if (snapshot.actions.pause.pressed) togglePause()
334
+ // a key for one piece of UI listens on that element:
335
+ dialog.addEventListener("keydown", (event) => { if (event.key === "ArrowDown") { event.preventDefault(); focusNext() } })
336
+ ```
337
+
338
+ Reports a `keydown`, `keyup`, or `keypress` listener added to `window`, `document`, `document.body`, or `document.documentElement` (also as `globalThis.addEventListener` or a bare `addEventListener`) whose function calls `preventDefault()` on its event, written inline or declared in the same file by name. A listener that leaves the default alone (opening audio on the first key) and a listener on another element are not reported. A listener reached through a class member or another function (`window.addEventListener("keydown", this.onKey)`) is not followed. For "press any key", use `Keyboard.presses(window)`.
339
+
314
340
  ## Built-in rules that pair well
315
341
 
316
342
  Some of oxlint's own rules catch Ritmo mistakes too. They are optional; turn on the ones the game wants.
package/dist/index.js CHANGED
@@ -6,8 +6,9 @@
6
6
  * clock, `Math.random`, engine-dependent math, or the page, or plays sound,
7
7
  * timers counted in floats, data that cannot be saved, casts that skip a
8
8
  * brand's check, state values that keep a previous state's fields, query
9
- * entities and data kept past their run, and runtime results that are
10
- * dropped. Every report names the Ritmo API to use instead.
9
+ * entities and data kept past their run, runtime results that are
10
+ * dropped, and host key listeners that take keys from the page's controls.
11
+ * Every report names the Ritmo API to use instead.
11
12
  *
12
13
  * Register the plugin in `.oxlintrc.json` with `"jsPlugins":
13
14
  * ["@typeonce/oxlint-plugin-ritmo"]`. Its rules are named `ritmo/<rule>`.
@@ -21,7 +22,7 @@
21
22
  * `ritmo/no-float-timers`, `ritmo/no-brand-cast`.
22
23
  * - Every file: `ritmo/handle-runtime-result`,
23
24
  * `ritmo/prefix-descriptor-and-system-names`, `ritmo/no-state-spread`,
24
- * `ritmo/no-kept-query-values`.
25
+ * `ritmo/no-kept-query-values`, `ritmo/use-keyboard-for-game-keys`.
25
26
  *
26
27
  * @module oxlint-plugin-ritmo
27
28
  */
@@ -35,6 +36,7 @@ import noKeptQueryValues from "./rules/no-kept-query-values.js";
35
36
  import noStateSpread from "./rules/no-state-spread.js";
36
37
  import prefixDescriptorAndSystemNames from "./rules/prefix-descriptor-and-system-names.js";
37
38
  import useClockForTime from "./rules/use-clock-for-time.js";
39
+ import useKeyboardForGameKeys from "./rules/use-keyboard-for-game-keys.js";
38
40
  import useOpsForMath from "./rules/use-ops-for-math.js";
39
41
  import useRandomForRandomness from "./rules/use-random-for-randomness.js";
40
42
  export default definePlugin({
@@ -50,7 +52,8 @@ export default definePlugin({
50
52
  "handle-runtime-result": handleRuntimeResult,
51
53
  "prefix-descriptor-and-system-names": prefixDescriptorAndSystemNames,
52
54
  "no-state-spread": noStateSpread,
53
- "no-kept-query-values": noKeptQueryValues
55
+ "no-kept-query-values": noKeptQueryValues,
56
+ "use-keyboard-for-game-keys": useKeyboardForGameKeys
54
57
  }
55
58
  });
56
59
  //# sourceMappingURL=index.js.map
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAE9C,OAAO,mBAAmB,MAAM,kCAAkC,CAAA;AAClE,OAAO,sBAAsB,MAAM,qCAAqC,CAAA;AACxE,OAAO,WAAW,MAAM,0BAA0B,CAAA;AAClD,OAAO,aAAa,MAAM,4BAA4B,CAAA;AACtD,OAAO,0BAA0B,MAAM,2CAA2C,CAAA;AAClF,OAAO,iBAAiB,MAAM,iCAAiC,CAAA;AAC/D,OAAO,aAAa,MAAM,4BAA4B,CAAA;AACtD,OAAO,8BAA8B,MAAM,+CAA+C,CAAA;AAC1F,OAAO,eAAe,MAAM,+BAA+B,CAAA;AAC3D,OAAO,aAAa,MAAM,6BAA6B,CAAA;AACvD,OAAO,sBAAsB,MAAM,sCAAsC,CAAA;AAEzE,eAAe,YAAY,CAAC;IAC1B,IAAI,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE;IACvB,KAAK,EAAE;QACL,oBAAoB,EAAE,eAAe;QACrC,2BAA2B,EAAE,sBAAsB;QACnD,kBAAkB,EAAE,aAAa;QACjC,0BAA0B,EAAE,sBAAsB;QAClD,gCAAgC,EAAE,0BAA0B;QAC5D,iBAAiB,EAAE,aAAa;QAChC,eAAe,EAAE,WAAW;QAC5B,uBAAuB,EAAE,mBAAmB;QAC5C,oCAAoC,EAAE,8BAA8B;QACpE,iBAAiB,EAAE,aAAa;QAChC,sBAAsB,EAAE,iBAAiB;KAC1C;CACF,CAAC,CAAA"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAE9C,OAAO,mBAAmB,MAAM,kCAAkC,CAAA;AAClE,OAAO,sBAAsB,MAAM,qCAAqC,CAAA;AACxE,OAAO,WAAW,MAAM,0BAA0B,CAAA;AAClD,OAAO,aAAa,MAAM,4BAA4B,CAAA;AACtD,OAAO,0BAA0B,MAAM,2CAA2C,CAAA;AAClF,OAAO,iBAAiB,MAAM,iCAAiC,CAAA;AAC/D,OAAO,aAAa,MAAM,4BAA4B,CAAA;AACtD,OAAO,8BAA8B,MAAM,+CAA+C,CAAA;AAC1F,OAAO,eAAe,MAAM,+BAA+B,CAAA;AAC3D,OAAO,sBAAsB,MAAM,uCAAuC,CAAA;AAC1E,OAAO,aAAa,MAAM,6BAA6B,CAAA;AACvD,OAAO,sBAAsB,MAAM,sCAAsC,CAAA;AAEzE,eAAe,YAAY,CAAC;IAC1B,IAAI,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE;IACvB,KAAK,EAAE;QACL,oBAAoB,EAAE,eAAe;QACrC,2BAA2B,EAAE,sBAAsB;QACnD,kBAAkB,EAAE,aAAa;QACjC,0BAA0B,EAAE,sBAAsB;QAClD,gCAAgC,EAAE,0BAA0B;QAC5D,iBAAiB,EAAE,aAAa;QAChC,eAAe,EAAE,WAAW;QAC5B,uBAAuB,EAAE,mBAAmB;QAC5C,oCAAoC,EAAE,8BAA8B;QACpE,iBAAiB,EAAE,aAAa;QAChC,sBAAsB,EAAE,iBAAiB;QACzC,4BAA4B,EAAE,sBAAsB;KACrD;CACF,CAAC,CAAA"}
@@ -0,0 +1,9 @@
1
+ /**
2
+ * Host code takes game keys through `Keyboard.actions` / `Keyboard.presses`,
3
+ * which leave keys the page is using (a focused control, an open dialog, a
4
+ * form field) to the page, not through a key listener on the whole page
5
+ * that prevents their default.
6
+ */
7
+ declare const _default: import("@oxlint/plugins").Rule;
8
+ export default _default;
9
+ //# sourceMappingURL=use-keyboard-for-game-keys.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"use-keyboard-for-game-keys.d.ts","sourceRoot":"","sources":["../../src/rules/use-keyboard-for-game-keys.ts"],"names":[],"mappings":"AAkDA;;;;;GAKG"}
@@ -0,0 +1,81 @@
1
+ import { defineRule } from "@oxlint/plugins";
2
+ import { constValue, docsUrl, globalPath, stringValue } from "../internal/ast.js";
3
+ /** The listeners on the whole page, by the path `globalPath` gives (`window.addEventListener` is `addEventListener`). */
4
+ const pageListeners = new Set(["addEventListener", "document.addEventListener", "document.body.addEventListener", "document.documentElement.addEventListener"]);
5
+ const keyEvents = new Set(["keydown", "keyup", "keypress"]);
6
+ const isFunction = (node) => node !== null && node !== undefined && (node.type === "ArrowFunctionExpression" || node.type === "FunctionExpression" || node.type === "FunctionDeclaration");
7
+ /** The function a listener argument is: written inline, or a `const` or function declaration of the file it names. */
8
+ const listenerFunction = (context, node) => {
9
+ if (isFunction(node))
10
+ return node;
11
+ if (node.type !== "Identifier")
12
+ return undefined;
13
+ const value = constValue(context, node);
14
+ if (isFunction(value))
15
+ return value;
16
+ const variable = context.sourceCode.getScope(node).references.find((reference) => reference.identifier === node)?.resolved;
17
+ const definition = variable?.defs.length === 1 ? variable.defs[0] : undefined;
18
+ return definition?.type === "FunctionName" && isFunction(definition.node) ? definition.node : undefined;
19
+ };
20
+ /** Whether a parameter list binds `name`, so the event of an outer listener is shadowed inside. */
21
+ const binds = (params, name) => params.some((param) => param.type === "Identifier" && param.name === name);
22
+ /** Whether `node` calls `<name>.preventDefault()` anywhere inside, outside nested functions that rebind `name`. */
23
+ const preventsDefault = (node, name) => {
24
+ if (node.type === "CallExpression") {
25
+ const callee = node.callee;
26
+ if (callee.type === "MemberExpression" && !callee.computed && callee.property.type === "Identifier" && callee.property.name === "preventDefault" &&
27
+ callee.object.type === "Identifier" && callee.object.name === name)
28
+ return true;
29
+ }
30
+ if (isFunction(node) && binds(node.params, name))
31
+ return false;
32
+ for (const [key, value] of Object.entries(node)) {
33
+ if (key === "parent")
34
+ continue;
35
+ const children = Array.isArray(value) ? value : [value];
36
+ for (const child of children) {
37
+ if (typeof child === "object" && child !== null && typeof child.type === "string" && preventsDefault(child, name))
38
+ return true;
39
+ }
40
+ }
41
+ return false;
42
+ };
43
+ /**
44
+ * Host code takes game keys through `Keyboard.actions` / `Keyboard.presses`,
45
+ * which leave keys the page is using (a focused control, an open dialog, a
46
+ * form field) to the page, not through a key listener on the whole page
47
+ * that prevents their default.
48
+ */
49
+ export default defineRule({
50
+ meta: {
51
+ type: "problem",
52
+ docs: {
53
+ description: "Take game keys with Keyboard.actions, not a key listener on window or document that calls preventDefault().",
54
+ url: docsUrl("use-keyboard-for-game-keys")
55
+ },
56
+ messages: {
57
+ pageListener: "A `{{type}}` listener on the whole page that calls `preventDefault()` also takes Enter, Space, and the arrows from a focused button, link, or open dialog, so the page's controls stop working by keyboard (games hide this with `tabIndex = -1` or `blur()`). Bind the key with `Keyboard.actions(window, bindings)` from `@typeonce/ritmo-browser` and read its `pressed` edge each frame (one-shot keys like Escape or M too; `Keyboard.presses(window)` for any key): it leaves keys the page is using to the page. A key for one piece of UI (a dialog's Escape, a menu's arrows) listens on that element instead."
58
+ },
59
+ schema: []
60
+ },
61
+ create(context) {
62
+ return {
63
+ CallExpression(node) {
64
+ const path = globalPath(context, node.callee);
65
+ if (path === undefined || !pageListeners.has(path))
66
+ return;
67
+ const type = stringValue(node.arguments[0]);
68
+ const listener = node.arguments[1];
69
+ if (type === undefined || !keyEvents.has(type) || listener === undefined)
70
+ return;
71
+ const handler = listenerFunction(context, listener);
72
+ const event = handler?.params[0];
73
+ if (handler === undefined || handler.body === null || event === undefined || event.type !== "Identifier")
74
+ return;
75
+ if (preventsDefault(handler.body, event.name))
76
+ context.report({ node, messageId: "pageListener", data: { type } });
77
+ }
78
+ };
79
+ }
80
+ });
81
+ //# sourceMappingURL=use-keyboard-for-game-keys.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"use-keyboard-for-game-keys.js","sourceRoot":"","sources":["../../src/rules/use-keyboard-for-game-keys.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@typeonce/oxlint-plugin-ritmo",
3
- "version": "0.23.0",
3
+ "version": "0.24.0",
4
4
  "description": "Oxlint rules for Ritmo games: deterministic, headless simulation code and checked runtime results",
5
5
  "author": "Sandro Maglione",
6
6
  "license": "MIT",
package/src/index.ts CHANGED
@@ -6,8 +6,9 @@
6
6
  * clock, `Math.random`, engine-dependent math, or the page, or plays sound,
7
7
  * timers counted in floats, data that cannot be saved, casts that skip a
8
8
  * brand's check, state values that keep a previous state's fields, query
9
- * entities and data kept past their run, and runtime results that are
10
- * dropped. Every report names the Ritmo API to use instead.
9
+ * entities and data kept past their run, runtime results that are
10
+ * dropped, and host key listeners that take keys from the page's controls.
11
+ * Every report names the Ritmo API to use instead.
11
12
  *
12
13
  * Register the plugin in `.oxlintrc.json` with `"jsPlugins":
13
14
  * ["@typeonce/oxlint-plugin-ritmo"]`. Its rules are named `ritmo/<rule>`.
@@ -21,7 +22,7 @@
21
22
  * `ritmo/no-float-timers`, `ritmo/no-brand-cast`.
22
23
  * - Every file: `ritmo/handle-runtime-result`,
23
24
  * `ritmo/prefix-descriptor-and-system-names`, `ritmo/no-state-spread`,
24
- * `ritmo/no-kept-query-values`.
25
+ * `ritmo/no-kept-query-values`, `ritmo/use-keyboard-for-game-keys`.
25
26
  *
26
27
  * @module oxlint-plugin-ritmo
27
28
  */
@@ -36,6 +37,7 @@ import noKeptQueryValues from "./rules/no-kept-query-values.ts"
36
37
  import noStateSpread from "./rules/no-state-spread.ts"
37
38
  import prefixDescriptorAndSystemNames from "./rules/prefix-descriptor-and-system-names.ts"
38
39
  import useClockForTime from "./rules/use-clock-for-time.ts"
40
+ import useKeyboardForGameKeys from "./rules/use-keyboard-for-game-keys.ts"
39
41
  import useOpsForMath from "./rules/use-ops-for-math.ts"
40
42
  import useRandomForRandomness from "./rules/use-random-for-randomness.ts"
41
43
 
@@ -52,6 +54,7 @@ export default definePlugin({
52
54
  "handle-runtime-result": handleRuntimeResult,
53
55
  "prefix-descriptor-and-system-names": prefixDescriptorAndSystemNames,
54
56
  "no-state-spread": noStateSpread,
55
- "no-kept-query-values": noKeptQueryValues
57
+ "no-kept-query-values": noKeptQueryValues,
58
+ "use-keyboard-for-game-keys": useKeyboardForGameKeys
56
59
  }
57
60
  })
@@ -0,0 +1,85 @@
1
+ import { defineRule } from "@oxlint/plugins"
2
+ import type { Context, ESTree } from "@oxlint/plugins"
3
+
4
+ import { constValue, docsUrl, globalPath, stringValue } from "../internal/ast.ts"
5
+
6
+ /** The listeners on the whole page, by the path `globalPath` gives (`window.addEventListener` is `addEventListener`). */
7
+ const pageListeners = new Set(["addEventListener", "document.addEventListener", "document.body.addEventListener", "document.documentElement.addEventListener"])
8
+
9
+ const keyEvents = new Set(["keydown", "keyup", "keypress"])
10
+
11
+ type FunctionNode = ESTree.ArrowFunctionExpression | ESTree.Function
12
+
13
+ const isFunction = (node: ESTree.Node | null | undefined): node is FunctionNode =>
14
+ node !== null && node !== undefined && (node.type === "ArrowFunctionExpression" || node.type === "FunctionExpression" || node.type === "FunctionDeclaration")
15
+
16
+ /** The function a listener argument is: written inline, or a `const` or function declaration of the file it names. */
17
+ const listenerFunction = (context: Context, node: ESTree.Node): FunctionNode | undefined => {
18
+ if (isFunction(node)) return node
19
+ if (node.type !== "Identifier") return undefined
20
+ const value = constValue(context, node)
21
+ if (isFunction(value)) return value
22
+ const variable = context.sourceCode.getScope(node).references.find((reference) => reference.identifier === node)?.resolved
23
+ const definition = variable?.defs.length === 1 ? variable.defs[0] : undefined
24
+ return definition?.type === "FunctionName" && isFunction(definition.node) ? definition.node : undefined
25
+ }
26
+
27
+ /** Whether a parameter list binds `name`, so the event of an outer listener is shadowed inside. */
28
+ const binds = (params: ReadonlyArray<ESTree.ParamPattern>, name: string): boolean =>
29
+ params.some((param) => param.type === "Identifier" && param.name === name)
30
+
31
+ /** Whether `node` calls `<name>.preventDefault()` anywhere inside, outside nested functions that rebind `name`. */
32
+ const preventsDefault = (node: ESTree.Node, name: string): boolean => {
33
+ if (node.type === "CallExpression") {
34
+ const callee = node.callee
35
+ if (
36
+ callee.type === "MemberExpression" && !callee.computed && callee.property.type === "Identifier" && callee.property.name === "preventDefault" &&
37
+ callee.object.type === "Identifier" && callee.object.name === name
38
+ ) return true
39
+ }
40
+ if (isFunction(node) && binds(node.params, name)) return false
41
+ for (const [key, value] of Object.entries(node)) {
42
+ if (key === "parent") continue
43
+ const children: ReadonlyArray<unknown> = Array.isArray(value) ? value : [value]
44
+ for (const child of children) {
45
+ if (typeof child === "object" && child !== null && typeof (child as { readonly type?: unknown }).type === "string" && preventsDefault(child as ESTree.Node, name)) return true
46
+ }
47
+ }
48
+ return false
49
+ }
50
+
51
+ /**
52
+ * Host code takes game keys through `Keyboard.actions` / `Keyboard.presses`,
53
+ * which leave keys the page is using (a focused control, an open dialog, a
54
+ * form field) to the page, not through a key listener on the whole page
55
+ * that prevents their default.
56
+ */
57
+ export default defineRule({
58
+ meta: {
59
+ type: "problem",
60
+ docs: {
61
+ description: "Take game keys with Keyboard.actions, not a key listener on window or document that calls preventDefault().",
62
+ url: docsUrl("use-keyboard-for-game-keys")
63
+ },
64
+ messages: {
65
+ pageListener:
66
+ "A `{{type}}` listener on the whole page that calls `preventDefault()` also takes Enter, Space, and the arrows from a focused button, link, or open dialog, so the page's controls stop working by keyboard (games hide this with `tabIndex = -1` or `blur()`). Bind the key with `Keyboard.actions(window, bindings)` from `@typeonce/ritmo-browser` and read its `pressed` edge each frame (one-shot keys like Escape or M too; `Keyboard.presses(window)` for any key): it leaves keys the page is using to the page. A key for one piece of UI (a dialog's Escape, a menu's arrows) listens on that element instead."
67
+ },
68
+ schema: []
69
+ },
70
+ create(context) {
71
+ return {
72
+ CallExpression(node) {
73
+ const path = globalPath(context, node.callee)
74
+ if (path === undefined || !pageListeners.has(path)) return
75
+ const type = stringValue(node.arguments[0])
76
+ const listener = node.arguments[1]
77
+ if (type === undefined || !keyEvents.has(type) || listener === undefined) return
78
+ const handler = listenerFunction(context, listener)
79
+ const event = handler?.params[0]
80
+ if (handler === undefined || handler.body === null || event === undefined || event.type !== "Identifier") return
81
+ if (preventsDefault(handler.body, event.name)) context.report({ node, messageId: "pageListener", data: { type } })
82
+ }
83
+ }
84
+ }
85
+ })