diff --git a/.changeset/open-modal-owns-keys.md b/.changeset/open-modal-owns-keys.md new file mode 100644 index 00000000..e4e6c3e3 --- /dev/null +++ b/.changeset/open-modal-owns-keys.md @@ -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 ``, focus fell to `` 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 `` 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 ``) 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 ``) now gets only the dialog's. diff --git a/.changeset/ui-playbook-dom-controls.md b/.changeset/ui-playbook-dom-controls.md new file mode 100644 index 00000000..1d79f53b --- /dev/null +++ b/.changeset/ui-playbook-dom-controls.md @@ -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 ``, 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. diff --git a/packages/browser/README.md b/packages/browser/README.md index 1019e5ac..6d6d2bb7 100644 --- a/packages/browser/README.md +++ b/packages/browser/README.md @@ -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` (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. diff --git a/packages/browser/src/Keyboard.ts b/packages/browser/src/Keyboard.ts index 79b45369..3c1f62cb 100644 --- a/packages/browser/src/Keyboard.ts +++ b/packages/browser/src/Keyboard.ts @@ -30,10 +30,11 @@ * * Keys the page is using are left to the page: a key that goes down in a * form field (`` of any type, `