Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 28 additions & 0 deletions .changeset/open-modal-owns-keys.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
---
"@typeonce/ritmo-browser": minor
---

**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.

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.

What a game may need to change:

- An `aria-modal="true"` element left shown during play now takes every key. Hide it when its menu closes, or remove the attribute:

```ts
menu.hidden = true // or menu.hidePopover(), or menu.removeAttribute("aria-modal")
```

- 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:

```ts
document.addEventListener("keydown", (event) => {
if (event.key === "Escape" && menu.matches(":popover-open")) {
event.preventDefault()
menu.hidePopover()
}
})
```

- 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.
5 changes: 5 additions & 0 deletions .changeset/ui-playbook-dom-controls.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@typeonce/ritmo": patch
---

The `ritmo` skill's UI playbook (`ui-and-render.md`) gains two steps for DOM controls and menus: build each control once and update it in place, never rewriting a region that holds one, and give it a name a test can find; a menu that stops play is a modal (`showModal()` on a `<dialog>`, or an `aria-modal` element that moves focus in, keeps it there, and makes the page behind inert itself), whose `cancel` and `close` are intents, with a `popover="manual"` for a splash or wipe over it and a modal dialog of its own for a layer the player presses.
2 changes: 1 addition & 1 deletion packages/browser/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Browser integrations for ritmo:

- `BrowserTickSource`: animation frames as a tick source for the core fixed-step loop.
- `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)).
- 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, inside an open modal dialog, or 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.
- 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.
- `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.
- `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.

Expand Down
95 changes: 85 additions & 10 deletions packages/browser/src/Keyboard.ts
Original file line number Diff line number Diff line change
Expand Up @@ -30,10 +30,11 @@
*
* Keys the page is using are left to the page: a key that goes down in a
* form field (`<input>` of any type, `<textarea>`, `<select>`,
* contenteditable), or inside an open modal dialog (`<dialog>` opened with
* `showModal()`, or `aria-modal="true"`), or that a listener nearer the
* target already handled with `preventDefault()` (a menu's arrows, a
* slider's keys), and Enter, Space, and Tab on a control the player reached
* contenteditable), or while a modal dialog is open (a `<dialog>` opened
* with `showModal()`, or a shown `aria-modal="true"` element), wherever
* focus is, or that a listener nearer the target already handled with
* `preventDefault()` (a menu's arrows, a slider's keys), and Enter, Space,
* and Tab on a control the player reached
* by keyboard (Tab to a button, link, tab, or any focusable element: the
* browser shows it with `:focus-visible`) press no action and are not
* `preventDefault`-ed. So a name field receives "wasd" and the player does
Expand Down Expand Up @@ -129,9 +130,24 @@ export type { Direction }
* - the target is a form field: its `tagName` is `INPUT` (any type,
* checkboxes and buttons included), `TEXTAREA`, or `SELECT`, or its
* `isContentEditable` is `true`;
* - the target is inside an open modal dialog: `closest` finds a
* `dialog:modal` (opened with `showModal()`) or an `[aria-modal="true"]`
* element, however the dialog was opened;
* - a modal dialog is open, wherever focus is: `closest` from the target
* finds a `dialog:modal` (opened with `showModal()`) or an
* `[aria-modal="true"]` element, or the target's document (its
* `ownerDocument`, or the target itself when it has `querySelector`) holds
* a `dialog:modal`, or an `[aria-modal="true"]` element that is shown:
* its `checkVisibility({ visibilityProperty: true, opacityProperty: true })`
* returns `true`. So a menu keeps its keys after a redraw deleted the
* focused button and dropped focus to `<body>`, and Escape still closes
* it. 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`: the player no longer sees the menu. A script that
* hides an `aria-modal` menu on a key calls `preventDefault()` on it (the
* first rule): it runs before a `window` host hears the key, and the menu
* it hid no longer counts. Not seen: a modal inside a shadow root (the
* target is then the shadow host, and the document query does not look
* inside it). A modal in another document (an iframe) is modal only
* there and leaves this host's keys alone;
* - the key is Enter, Space, or Tab (the keys a browser itself acts on for
* a focused control: press it, move focus on) and the target took focus
* by keyboard: it matched `:focus-visible` when its `focusin` reached the
Expand All @@ -155,9 +171,12 @@ export type { Direction }
*
* The target is read by shape, not `instanceof`, so it works across
* iframes, and a test host types into a field by passing
* `{ tagName: "INPUT" }` or `{ isContentEditable: true }`, and focuses a
* `{ tagName: "INPUT" }` or `{ isContentEditable: true }`, focuses a
* control by keyboard by sending `focusin` with a target whose
* `matches(":focus-visible")` returns `true`.
* `matches(":focus-visible")` returns `true`, and opens a modal by giving
* the target an `ownerDocument` whose `querySelector("dialog:modal")`
* returns an element. A target without those members leaves the key with
* the game.
*/
export interface KeyEvent {
readonly key: string
Expand Down Expand Up @@ -225,6 +244,59 @@ const hasAncestor = (target: object, selector: string): boolean => {
const isInsideModal = (target: object): boolean =>
hasAncestor(target, "[aria-modal=\"true\"]") || hasAncestor(target, "dialog:modal")

/** The members of a document the module reads. */
interface DocumentShape {
readonly ownerDocument?: unknown
readonly querySelector?: unknown
readonly querySelectorAll?: unknown
}

/** The document a key went down in: the target's `ownerDocument`, or the target itself when it is one (it can query). */
const documentOf = (target: object): object | null => {
const { ownerDocument, querySelector } = target as DocumentShape
if (typeof ownerDocument === "object" && ownerDocument !== null) return ownerDocument
return typeof querySelector === "function" ? target : null
}

/**
* Whether an `aria-modal` element is shown. A closed one often stays in the
* page with its attribute (`hidden`, a closed popover, `display: none`), and
* one fading out at `opacity: 0` is gone for the player. An element that
* cannot answer is not shown.
*/
const isShown = (element: unknown): boolean => {
if (typeof element !== "object" || element === null) return false
const { checkVisibility } = element as { readonly checkVisibility?: unknown }
if (typeof checkVisibility !== "function") return false
return (checkVisibility as (options: object) => unknown).call(element, { visibilityProperty: true, opacityProperty: true }) === true
}

/** Whether the document holds an open modal dialog, wherever focus is in it. */
const hasOpenModal = (document: object): boolean => {
const { querySelector, querySelectorAll } = document as DocumentShape
try {
if (typeof querySelector === "function") {
const dialog: unknown = (querySelector as (selector: string) => unknown).call(document, "dialog:modal")
if (dialog !== null && dialog !== undefined) return true
}
if (typeof querySelectorAll !== "function") return false
const elements: unknown = (querySelectorAll as (selector: string) => unknown).call(document, "[aria-modal=\"true\"]")
if (typeof elements !== "object" || elements === null || typeof (elements as { readonly length?: unknown }).length !== "number") return false
const list = elements as ArrayLike<unknown>
for (let index = 0; index < list.length; index++) if (isShown(list[index])) return true
return false
} catch {
return false
}
}

/** Whether a modal dialog is open for a key with this target, by the rule on {@link KeyEvent}. */
const isModalOpen = (target: object): boolean => {
if (isInsideModal(target)) return true
const document = documentOf(target)
return document !== null && hasOpenModal(document)
}

/**
* The key events a `Keyboard.actions` device prevented: another device on
* the same host sees them as `defaultPrevented`, and they are still the game's.
Expand Down Expand Up @@ -267,7 +339,7 @@ const pageKeys = (host: KeyboardHost): PageKeys => {
if (event.defaultPrevented === true && !preventedByKeyboard.has(event)) return true
const target = event.target ?? null
if (target === null) return false
return isEditableTarget(target) || isInsideModal(target) || isControlPress(event, target)
return isEditableTarget(target) || isControlPress(event, target) || isModalOpen(target)
},
ownsWhileCapturing(event) {
const target = event.target ?? null
Expand Down Expand Up @@ -622,6 +694,9 @@ export const actions = <const B extends Bindings>(
}
tokens.push(codeToken(event.code))
}
// A key bound to no action presses nothing and is not prevented, so the
// page's rule (which may query the document) is not asked for it.
if (!tokens.some((token) => actionsByToken.has(token))) return
// A key the page is using belongs to the page; a shortcut belongs to the
// browser. Their releases are still processed by `onKeyUp`.
if (page.owns(event) || (leavesShortcuts && isShortcut(event))) return
Expand Down
Loading
Loading