Files
scadaproj/impeccable/MxAccessGateway.md
T
2026-11-13 14:40:42 -05:00

115 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# MxAccessGateway — Impeccable UI recommendations
Reviewed 2026-11-12 · source snapshot `7481b959` · Operate mode.
The dashboard already consumes `ZB.MOM.WW.Theme` **0.5.0** (Server.csproj:18), with `ThemeHead`, `ThemeScripts`, `ThemeShell`, and an app-local state adapter wrapping `StatusPill`. Keep its blue accent. The highest-value update is to make Galaxy browsing as usable by keyboard and touch as it is by mouse.
[Open proposed mockup](mockups/MxAccessGateway.html) · [Review index](index.html) · [Shared direction](SHARED-DESIGN-SYSTEM.md).
This is a source-backed review and design proposal. Production applications, live credentials, deployed data, browser keyboard behavior, and measured performance were not exercised. Mockups use illustrative data and demonstrate proposed patterns; they are not screenshots of the existing application. No production source was modified.
## Summary
3 P1, 4 P2, 1 P3 recommendations; no proven P0. Strong shared chrome, but mouse-only attribute actions, unmanaged modal focus and unnamed browse search warrant the first implementation pass. Numeric audit scores are withheld because runtime, load and assistive-technology checks were not performed.
## Shared visual contract
Keep IBM Plex Sans for reading and Plex Mono for identifiers, timestamps, and aligned values; warm paper, white panels, thin neutral rules, compact navigation, and one clear page heading. Use the shared Theme package for chrome and primitives. Shared means the same spacing, field, table, notice, focus, status, and responsive rules. Preserve explicitly permitted product accents. Do not fork a theme per page or introduce a separate dark dashboard. The mockups show accessible status ink and taller touch targets as proposals for the shared library, not new app-local token copies.
## Verification and release gate
At 1440 × 900, 1024 × 768, 390 × 844 and 200% zoom, verify that only intentional table regions scroll horizontally; headings, filters, notices and footer actions remain visible. Keyboard-test navigation, search, detail disclosure and all dialogs. Confirm text names and state announcements with a screen reader; measure text contrast (4.5:1) and non-text focus/control contrast (3:1). On coarse pointers, offer 44px targets without forcing every desktop data row to become tall. Test long tag paths, empty results, unavailable dependencies, stale snapshots, denied access and a slow operation that succeeds after several seconds.
A source detector ran once across the gateway dashboard and ignitionoee router/registry component directories. It returned `[]`: see [gateways-detector.json](evidence/gateways-detector.json). This is a narrow mechanical result, not an accessibility pass; manual source findings below remain valid. CSS in separate host asset directories and Perspective JSON are outside that invocation. No detector false positives required dismissal.
### MX-01 · P1 · Make the subscription workflow keyboard and touch accessible
**Evidence:** [src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Shared/BrowseTreeNodeView.razor:69](/Users/dohertj2/Desktop/MxAccessGateway/src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Shared/BrowseTreeNodeView.razor:69).
**Owner:** app interaction; shared tree/disclosure pattern. **Impact:** adding an attribute depends on double-click or right-click on a non-focusable `div`; the advertised primary workflow is unavailable to keyboard users. The node-name span is also click-only; its separate toggle button has a generic name and no expanded state. **Recommendation:** render an explicit “Watch attribute” button per attribute or selected-row action, use a named node button with `aria-expanded` and `aria-controls`, and retain context menus as an accelerator. **Acceptance:** Tab → node → expand → attribute → Watch completes without mouse; a touch user can watch a tag with one visible action. WCAG 2.1.1 / 4.1.2. **Command:** `$impeccable harden`.
### MX-02 · P1 · Replace presentation-only modal overlays with managed dialogs
**Evidence:** [src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Shared/ConfirmDialog.razor:4](/Users/dohertj2/Desktop/MxAccessGateway/src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Shared/ConfirmDialog.razor:4).
**Owner:** shared dialog primitive plus app consumers. **Impact:** this component renders an `aria-modal` overlay without focus entry, focus containment, Escape handling or return focus. API-key creation repeats the pattern at `Pages/ApiKeysPage.razor:55`. The parent app links only shared nav-state JavaScript; the component itself contains no focus management. **Recommendation:** introduce a native dialog or a complete managed modal contract, preserve busy/cancel semantics, and use the same contract for confirmation and key creation. **Acceptance:** initial focus is deliberate; Tab stays within the dialog; Escape cancels when safe; focus returns to the invoking control; underlying writes cannot receive focus. WCAG 2.4.3 / 2.1.1. **Command:** `$impeccable harden`.
### MX-03 · P1 · Give browse search a persistent accessible label
**Evidence:** [src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/BrowsePage.razor:27](/Users/dohertj2/Desktop/MxAccessGateway/src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/BrowsePage.razor:27).
**Owner:** app, following shared field contract. **Impact:** search has only a placeholder; its purpose disappears while typing and it has no explicit accessible name in markup. **Recommendation:** add a visible `label for`, input `id`, and search hint/result status association. **Acceptance:** the search is announced as “Filter Galaxy attributes”, the hint remains after entry, and a zero-result message includes Clear search. WCAG 3.3.2 / 4.1.2. **Command:** `$impeccable clarify`.
### MX-04 · P2 · Turn the overview into an exception-first operating view
**Evidence:** [src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/DashboardHome.razor:21](/Users/dohertj2/Desktop/MxAccessGateway/src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/DashboardHome.razor:21).
**Owner:** app composition. **Impact:** eight equally weighted metrics followed by six Galaxy metrics make faults compete with uptime and lifetime totals. “View browse details” links to repository summary rather than live Browse. **Recommendation:** lead with a compact gateway/freshness strip and actionable faults, followed by sessions/workers/queue context. Put cumulative counters and repository size under a labeled disclosure; distinguish Repository status and Browse attributes destinations. **Acceptance:** from the first viewport, an operator can identify a fault and open the responsible session without reading every metric. Preserve every existing counter in the detail disclosure. **Command:** `$impeccable distill`.
### MX-05 · P2 · Remove copied theme shades and local component styling
**Evidence:** [src/ZB.MOM.WW.MxGateway.Server/wwwroot/css/site.css:134](/Users/dohertj2/Desktop/MxAccessGateway/src/ZB.MOM.WW.MxGateway.Server/wwwroot/css/site.css:134).
**Owner:** Theme first, then local cleanup. **Evidence:** local zebra/hover fills at 134/144, button fills at 202–226, alert shades at 253–254, browse row fills at 324/340 and attribute flags at 398 repeat shared colors. **Impact:** a shared contrast or palette fix leaves these islands behind. **Recommendation:** replace literal neutral/status shades with existing tokens, move genuinely shared field/button/notice rules into Theme, retain browse geometry locally, and compare before deleting overlapping selectors. **Acceptance:** changes to shared hover/status tokens reach app tables, notices and tree flags; a local color scan permits only documented domain encodings. **Command:** `$impeccable extract`.
### MX-06 · P2 · Expose complete errors without hover and announce recovery
**Evidence:** [src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Shared/BrowseTreeNodeView.razor:48](/Users/dohertj2/Desktop/MxAccessGateway/src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Shared/BrowseTreeNodeView.razor:48).
**Owner:** app + shared notice/detail pattern. **Impact:** tree-load failures are abbreviated with the full error available only in `title`; hover does not serve touch and screen-reader users reliably. Browse search/live-read errors at `BrowsePage.razor:43/125` also lack an explicit alert/status role. **Recommendation:** show a plain-language summary, Retry and expandable safe diagnostic detail; use one polite status for recovery and an alert for a user-triggered failure. **Acceptance:** a failed child load can be read and retried without collapsing the entire tree or losing subscriptions. No repetitive announcement on every 2-second refresh. **Command:** `$impeccable harden`.
### MX-07 · P2 · Increase browse control hit areas without sacrificing data density
**Evidence:** [src/ZB.MOM.WW.MxGateway.Server/wwwroot/css/site.css:344](/Users/dohertj2/Desktop/MxAccessGateway/src/ZB.MOM.WW.MxGateway.Server/wwwroot/css/site.css:344).
**Owner:** shared control sizing + local tree geometry. **Impact:** the tree toggle is 1.1rem square; the subscription remove control is also compact. These are difficult targets on tablets used beside equipment. **Recommendation:** keep a compact visible chevron but expand its button hit area; apply the shared coarse-pointer rule consistently and make overflow local to tree/table regions. **Acceptance:** 44px coarse-pointer targets, readable wrapped metadata at 390px, no document-level horizontal scrolling, and a long tag does not hide the remove action. **Command:** `$impeccable adapt`.
### MX-08 · P3 · Normalize heading and action language across the family
**Evidence:** [src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Layout/MainLayout.razor:10](/Users/dohertj2/Desktop/MxAccessGateway/src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Layout/MainLayout.razor:10).
**Owner:** shared terminology + app. **Impact:** the rail says Dashboard while the landing page says Overview, and sign-out capitalization differs between consumers. **Recommendation:** prefer Overview, API keys, Sign out, Refresh, and sentence case page titles throughout the family; keep runtime state strings intact where their exact value helps diagnostics. **Acceptance:** rail, document title and visible heading identify the same destination. Preserve stable nav keys. **Command:** `$impeccable clarify`.
## What to keep
- Shared chrome and `StatusBadge` domain-to-token adapter; do not move runtime state mapping into the UI library.
- Lazy child loading, capped search results and explicit no-cache/no-match states.
- Text labels inside status pills, scoped column headings, table scrolling, busy flags and confirmation for session management.
- Policy-aligned Alarms and Secrets navigation; API keys intentionally remain readable to Viewers.
## Coverage and implementation order
Deep inspection: Browse and recursive tree; shared confirmation/status components; Overview; API-key create markup; shell; host CSS. All remaining route markup was scanned for headers, data containers, feedback and action patterns. This does not assert every event handler or permission branch was executed. `/admin/secrets` is mounted from the common Secrets UI and is covered by the family shared-UI review.
| Route | Source | Coverage |
| --- | --- | --- |
| `/alarms` | `src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/AlarmsPage.razor` | Source scanned |
| `/apikeys` | `src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/ApiKeysPage.razor` | Source scanned |
| `/browse` | `src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/BrowsePage.razor` | Source scanned |
| `/` | `src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/DashboardHome.razor` | Source scanned |
| `/events` | `src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/EventsPage.razor` | Source scanned |
| `/galaxy` | `src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/GalaxyPage.razor` | Source scanned |
| `/login` | `src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/Login.razor` | Source scanned |
| `/sessions/{SessionId}` | `src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/SessionDetailsPage.razor` | Source scanned |
| `/sessions` | `src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/SessionsPage.razor` | Source scanned |
| `/settings` | `src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/SettingsPage.razor` | Source scanned |
| `/workers` | `src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/WorkersPage.razor` | Source scanned |
1. `$impeccable harden`: MX-01/02 and MX-06, then `$impeccable clarify`: MX-03.
2. `$impeccable extract` and `$impeccable adapt`: MX-05/07 after the shared release is available.
3. `$impeccable distill` / `$impeccable clarify`: MX-04/08.
4. `$impeccable polish` after interaction and responsive acceptance checks pass; rerun `$impeccable audit` on the running app.
The mockup shows a proposed exception-first Overview, persistent state/freshness context, session detail disclosure and a functional local session filter. Restart, close-session and key operations are deliberately absent from this static artifact.
## Rendered proposal previews
These are proposed UI artifacts with illustrative data, not screenshots of the current application. All use the same shared stylesheet. See [verification and limits](VERIFICATION.md).
### MxAccessGateway
[Interactive HTML](mockups/MxAccessGateway.html) · [Desktop PNG](evidence/MxAccessGateway-desktop.png) · [Mobile PNG](evidence/MxAccessGateway-mobile.png)
![Proposed MxAccessGateway desktop UI](evidence/MxAccessGateway-desktop.png)