[pournasserian]

Refs #2434

What

admin.js becomes the one interop module #2434 asks for. It handles focus trapping, the roving tab index and global keyboard shortcuts, alongside the overlays, the theme and the reconnect display it already ran. It stays a set of delegated document listeners that read the page when an event arrives, so it works over an interactive-server circuit, while the circuit is down and after a reconnect, with no per-component interop.

• Global keyboard shortcuts. An element declares its keys in aria-keyshortcuts, ARIA's own attribute, so assistive technology announces them too. For example, aria-keyshortcuts="Control+K Meta+K" means either chord.
  • On a matching key the module clicks a button or link and focuses anything else.
  • Letters and digits also match by their physical key, so a shortcut works on a Persian or Arabic layout and with Option on a Mac.
  • A shortcut without Control, Alt or Meta waits while someone types in a field or a menu.
  • While a modal dialog is open, only the shortcuts inside it apply.
  • Disabled, hidden and inert elements are skipped.
  • The page is read at the time of the key, so shortcuts on content Blazor renders later, or renders again after a reconnect, work with no registration.
• One roving tab index. rove and roveIndex replace the separate code in menus and tabs: one item is in the tab order, the arrow keys, Home and End move focus, and horizontal groups follow the direction. Command keeps focus in its input and moves aria-activedescendant with the same wrap-around.
• Focus trapping for every control. Each keydown handler now reports whether it used the key, and a key none of them used reaches the trap. Before this, Tab on a Command input or a menu trigger inside a dialog skipped the trap and left the modal. Tabs already had this fix from Add the Tabs, Sheet, Popover, Tooltip and Toast components #2493.
• Shortcuts on /ui. Ctrl+K or ⌘K focuses the command palette. Alt+T focuses the toasts, as Sonner does; the Toaster region now has tabindex="-1" and aria-keyshortcuts="Alt+T".
• CONTRIBUTING.md: how to declare a shortcut, and that admin.js is the only script and no component calls into it.

Boxes on #2434

To tick when this merges: "One small JavaScript interop module for what the platform does not cover: focus trapping, roving tab index and global keyboard shortcuts. It is the only JavaScript in the admin."

Why

• aria-keyshortcuts rather than a registry. A registry, in C# or in JavaScript, would have to be rebuilt after every render and after a reconnect, and someone would have to keep it in step with the markup. An attribute on the element is in the page whenever the element is, carries its own accessibility, and lets the module stay stateless.
• Click or focus. A shortcut stands in for the control it is declared on, so it does what activating that control does. A field or a region gets focus, which is what the palette and the toast region need.
• Typing wins over single keys. The desk will want single-key shortcuts. They must never fire while someone types a value or uses a menu's typeahead, so they only apply outside fields and menus.

No new dependency.

Tests

bUnit cannot run the module, so its keyboard behaviour was checked by hand; the tests pin what the module relies on:

• InteropModuleTests:
  • admin.js is the only script in wwwroot.
  • No component in the admin injects IJSRuntime.
  • Only App.razor loads scripts.
  • The showcase declares its shortcuts with aria-keyshortcuts.
• ToasterTests: the region is focusable from script only and declares Alt+T.

Checked by hand on /ui over a live circuit:

• Ctrl+K from a button moves focus to the command palette.
• With the circuit paused (Blazor.pauseCircuit(), reconnect card showing), Alt+T moves focus to the toast region and the dialog still opens.
• With the dialog open, Ctrl+K leaves focus inside it.
• After Blazor.resumeCircuit(), Ctrl+K works again.
• The menu, tabs and command keys behave as before.

dotnet build -warnaserror, the full suite and markdownlint pass locally.

Checklist

• Linked to an issue a maintainer has confirmed
• Targets v2
• Tests or docs updated where behaviour changed
• No tool-generated co-author trailers or footers