Files
lmxopcua/docs/ui-consistency/evidence/ot13-dialog-focus-recovery
2026-11-14 00:17:52 -05:00
..

Shared native dialog focus recovery

Owned production change: only wwwroot/js/dialog-focus.js, shared inside this AdminUI consumer. No ModalFrame API, managed wrapper, package, style, authorization or backend change. Existing one-active-overlay and id/generation contracts remain; no nesting framework was extracted.

Actual browser evidence in the Raw workflow exposed focus falling to body when Connect was removed. Disabling a focused mutation control has the same native DOM behavior. An element-only keydown trap cannot then receive Tab/Escape, so a busy dialog could lose keyboard containment and a dismissible read could stop responding to Escape.

Correction

Current-generation update now reanchors only when focus has left the current connected, non-inert modal, choosing its usable safe initial control or the modal root when busy has disabled every action. An already focused control/root is retained. Deliberate focus inside a different dialog is never stolen.

The original modal-local keydown listener remains in place so handled Escape stops before ancestor shortcuts, exactly as before. A document capture listener handles only outside-target gaps before background ancestor shortcuts; events whose targets are inside the modal are ignored by that fallback. This avoids double handling and preserves child-widget stopPropagation behavior. Both listeners are removed on deactivation. Current presentation identity/generation and other-dialog focus checks apply to keyboard handling; no global focusin hook, timer or MutationObserver expansion was added.

The root caller separately keeps its read-only Connect→Refresh node mounted with aria-disabled and server entry guards. This adapter correction is still needed for genuinely disabled mutation controls and removal gaps in any wrapper.

Meaningful native regressions

check_dialog_focus_recovery.py executes the actual production adapter in Chromium over a synthetic local document and recording receiver, with real DOM focus, disabled fieldsets, inert, Tab/Shift+Tab and Escape. It uses no application host, network, operational service or database.

  • red.json: four of six scenes failed; stale-generation and other-dialog positive controls passed.
  • red-complete.json: same four failures with 37 checks, including Escape reaching a background shortcut from the body gap. Busy/removed focus recovery, zero-control Tab/reverse-Tab containment and dismissible-read Escape were missing.
  • green-final.json: 9/9 scenes /51 checks passed, no page errors. The original six scenes plus child-handled Escape, local ancestor-shortcut ordering and deactivation listener cleanup all pass. Native disabling/removal produced the actual body-focus gap; the tests do not set a fabricated component field to simulate it. The separate document-key scene deliberately blurs the current root to reproduce the interval between DOM mutation and a subsequent update.
  • existing-native-final.json: 10/10 existing native adapter cases passed, covering safe entry, focus containment, removed/disabled/hidden/unfocusable trigger fallback, heading/landmark preference, preserved tabindex, and restored pre-existing inert/body state. The established check_native_dialog.py source was executed unchanged except redirecting its JSON destination into this owned evidence directory. Its original OT01 evidence was not overwritten.

Final production JS SHA-256: 7f63bd6c5181d0b70edc2e87e086fab4dfba96adabd7a19737f9b3b4f18296d5.

An intermediate document-only bubble implementation passed the six direct focus scenarios. Source review identified local ancestor ordering, so the local listener was retained. Parent then identified the outside-body-gap ordering case: outside-capture-red.json records two meaningful failures (7/9 scenes), because a body ancestor shortcut acted before the document bubble fallback. The final outside-target capture listener passes both cases while its inside-target skip preserves child/local handling. Intermediate logs are historical, not final source acceptance. No test assertion was relaxed.

Reproduce from the OtOpcUa repository root:

python3 infra/tools/ui-consistency/check_dialog_focus_recovery.py --output docs/ui-consistency/evidence/ot13-dialog-focus-recovery/green-final.json

This is native adapter behavior, not manual assistive-technology certification or a complete composed modal/fleet gate. All workers were notified of the exact frozen hash and must verify served bytes in their final source-linked native matrices. Managed tests were not rerun for this JavaScript-only change; final combined consumer tests remain coordinator-owned. The temporary browser contexts close at harness completion, and no host/service/container lifecycle was changed.

Bounded preactivation rollout observation

preactivation-investigation.json records four additional controlled native sequences against the same frozen source. With the external invoker focused when activation starts, both DOM-removal orders restore that invoker. If a synthetic sequence puts focus inside the dialog before activation starts, the adapter captures that internal control: removal before deactivation falls back to the page heading; deactivation before removal can finish on body after restoring the then-connected closing control. Safe initial Cancel, inert/body cleanup and error-free execution still occur.

This certifies capture semantics only. It does not reproduce ordinary-user timing in a composed Blazor modal, and the original UNS scratch observation had insufficient retained context to establish that cause. The coordinator accepted this as a bounded rollout note, not a reason to reopen shared source or the completed native matrices. Exact external invoker recovery in that synthetic schedule would require an explicit/pre-recorded invoker contract; no such new API or tracking hook was added. Normal initialized dialogs retain their verified opener/heading fallback behavior.