107 lines
12 KiB
Markdown
107 lines
12 KiB
Markdown
# HistorianGateway — Impeccable UI recommendations
|
||
|
||
Reviewed 2026-11-12 · source snapshot `fa9cf31` · Operate mode.
|
||
|
||
The server consumes Theme **0.5.0** (Server.csproj:30) and uses the shared shell, assets, panels, data tables and status pills. Keep its allowed green product accent (`MainLayout.razor:10`); status meaning remains common with blue-accent sisters. The main opportunity is to make point-in-time state, queries and diagnostic writes clearer.
|
||
|
||
[Open proposed mockup](mockups/HistorianGateway.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
|
||
|
||
1 P1 and 6 P2 recommendations; no demonstrated P0. The architecture already avoids duplicated live status on its landing page and lazily renders Galaxy nodes. Prioritize label associations, accessible diagnostics, freshness and write-intent review. No numerical quality score is assigned without runtime accessibility/performance evidence.
|
||
|
||
## 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.
|
||
|
||
### HG-01 · P1 · Associate every console label and control
|
||
|
||
**Evidence:** [src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/HistorianConsolePage.razor:28](/Users/dohertj2/Desktop/HistorianGateway/src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/HistorianConsolePage.razor:28).
|
||
|
||
**Owner:** app plus shared field API. **Impact:** query and write-test controls use standalone labels without `for`/`id` or an explicit accessible name; visible proximity does not associate them. **Recommendation:** give each query/write/event field a stable unique ID and associated label, group query vs historical write vs event write with headings/fieldsets, and associate validation help and errors. **Acceptance:** a screen reader announces Tag, Mode, Max values, Start UTC, End UTC and every diagnostic field unambiguously; clicking a label focuses its control. WCAG 1.3.1 / 3.3.2 / 4.1.2. **Command:** `$impeccable harden`.
|
||
|
||
### HG-02 · P2 · Place sampled time beside status and preserve stale context on failure
|
||
|
||
**Evidence:** [src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/StatusPage.razor:17](/Users/dohertj2/Desktop/HistorianGateway/src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/StatusPage.razor:17).
|
||
|
||
**Owner:** app adopting shared page-state/freshness pattern. **Impact:** the page is deliberately manual-refresh, but generated time is buried in the Gateway card (`:62`). A connectivity chip at the top can be read as current after a long unattended interval. `LoadAsync` at `:222` has `try/finally` but no page-local failure UI. Health has the same manual pattern at `HealthPage.razor:17/105`. **Recommendation:** place “Snapshot captured … UTC · Manual refresh” beside the title, preserve the last snapshot on retrieval failure, and show a recovery notice with Retry. **Acceptance:** initial failure, refresh failure and old-but-valid data are visually distinct; retry retains page context; no silent stale-success display. **Command:** `$impeccable harden`.
|
||
|
||
### HG-03 · P2 · Make diagnostic errors readable without hover
|
||
|
||
**Evidence:** [src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/HealthPage.razor:82](/Users/dohertj2/Desktop/HistorianGateway/src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/HealthPage.razor:82).
|
||
|
||
**Owner:** shared disclosure/detail pattern, app content. **Impact:** health descriptions and redundancy errors (`StatusPage.razor:199`) are abbreviated with only a title tooltip exposing the full value. **Recommendation:** a row details disclosure must reveal full safe text, affected dependency and next step; preserve short rows for scanning. **Acceptance:** keyboard/touch users can retrieve the same diagnostic content as a mouse user, copy identifiers, and return to the same row. **Command:** `$impeccable harden`.
|
||
|
||
### HG-04 · P2 · Separate and review historical write intent
|
||
|
||
**Evidence:** [src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/HistorianConsolePage.razor:130](/Users/dohertj2/Desktop/HistorianGateway/src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/HistorianConsolePage.razor:130).
|
||
|
||
**Owner:** app behavior. **Impact:** the Administrator write-test panel sits immediately beneath read-only history results and uses the same secondary-button treatment; a direct Insert value or Send event applies an actual operation. **Recommendation:** retain role gating and diagnostic-only copy; put writes in a clearly labeled disclosure or dedicated section and show a compact review of target, tag, UTC timestamp and operation before dispatch. A review is a new proposed behavior, not existing enforcement. **Acceptance:** queries remain one action; a write requires an explicit review/confirm step, names its target, prevents double-submit and preserves typed data after failure. **Command:** `$impeccable clarify`.
|
||
|
||
### HG-05 · P2 · Give Galaxy search and expansion recognizable names
|
||
|
||
**Evidence:** [src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/GalaxyBrowserPage.razor:54](/Users/dohertj2/Desktop/HistorianGateway/src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/GalaxyBrowserPage.razor:54).
|
||
|
||
**Owner:** app; reusable browse control pattern. **Impact:** search has only placeholder copy. Node buttons in `Shared/GalaxyTreeNodeView.razor:20` expose expanded state correctly but all announce “Toggle”; the clickable node-label span has no keyboard interaction. **Recommendation:** add a visible search label and count/clear control, name each toggle “Expand [object]” or “Collapse [object]”, and consolidate label plus chevron into a semantic button. **Acceptance:** the user can distinguish adjacent node actions and locate search after typing; preserve lazy rendering and the 300-hit cap. **Command:** `$impeccable harden`.
|
||
|
||
### HG-06 · P2 · Strengthen query result hierarchy and action feedback
|
||
|
||
**Evidence:** [src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/HistorianConsolePage.razor:80](/Users/dohertj2/Desktop/HistorianGateway/src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/HistorianConsolePage.razor:80).
|
||
|
||
**Owner:** shared field/notice/table patterns + app. **Impact:** Run is visually equivalent to secondary actions; unsuccessful query text is a muted paragraph (`:88`) and result context is only row count. **Recommendation:** name the primary action Run query, show busy status with `aria-busy`, a single polite result announcement, a distinct failure notice, and retain the submitted tag/range/mode beside results. Show zero samples as a successful empty result with a recovery suggestion. **Acceptance:** keyboard submission is possible; failure is distinguishable from an empty result; editing the next query does not silently relabel the previous result set. **Command:** `$impeccable clarify`.
|
||
|
||
### HG-07 · P2 · Flatten landing-page signposts while keeping their purpose
|
||
|
||
**Evidence:** [src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/Home.razor:13](/Users/dohertj2/Desktop/HistorianGateway/src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/Home.razor:13).
|
||
|
||
**Owner:** app composition. **Impact:** four equally sized panels duplicate rail destinations and require reading paragraphs before navigation. The intentional choice not to duplicate live status is sound. **Recommendation:** keep the landing page a signpost, using a concise grouped task list: Inspect gateway health, Browse Galaxy metadata, Query history; keep admin-only entry points role-gated. Do not add invented live metrics. **Acceptance:** all current destinations remain available and descriptive, and the first viewport distinguishes read-only browsing from diagnostic writing. **Command:** `$impeccable distill`.
|
||
|
||
## What to keep
|
||
|
||
- The green accent is an existing permitted shell override; it does not justify green variants of every component.
|
||
- Server-side role gating around diagnostic writes and API-key administration, one-time tokens and inline revoke confirmation.
|
||
- Manual refresh: keep it visible and honest rather than adding hidden polling everywhere.
|
||
- Lazy Galaxy rendering with independent expansion state and a capped flat search, which explicitly addresses large real hierarchies.
|
||
- Missing archive counts stay `n/a`, not zero (`StatusPage.razor:254`); keep unknown distinct from healthy.
|
||
|
||
## Coverage and implementation order
|
||
|
||
Deep inspection: Console query/write markup; Status and Health state/data handling; Galaxy browser and recursive node; API-key form; shell and CSS. Login and landing-page routing were scanned. Shared mounted Secrets UI belongs to the family shared-component review.
|
||
|
||
| Route | Source | Coverage |
|
||
| --- | --- | --- |
|
||
| `/apikeys` | `src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/ApiKeysPage.razor` | Source scanned |
|
||
| `/galaxy` | `src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/GalaxyBrowserPage.razor` | Source scanned |
|
||
| `/health` | `src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/HealthPage.razor` | Source scanned |
|
||
| `/console` | `src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/HistorianConsolePage.razor` | Source scanned |
|
||
| `/` | `src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/Home.razor` | Source scanned |
|
||
| `/login` | `src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/Login.razor` | Source scanned |
|
||
| `/status` | `src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/StatusPage.razor` | Source scanned |
|
||
|
||
1. `$impeccable harden`: HG-01, HG-02, HG-03 and HG-05.
|
||
2. `$impeccable clarify`: HG-04/06; `$impeccable distill`: HG-07.
|
||
3. `$impeccable adapt`: coarse-pointer tree hit areas, horizontal table containment, long targets and 200% zoom.
|
||
4. `$impeccable polish`, then a live `$impeccable audit`.
|
||
|
||
The mockup focuses on the proposed Console: an explicitly labeled query, submitted-result context, quality text, and a guarded diagnostic-write disclosure. Its “Show sample results” control only reveals local illustrative rows and never contacts a historian.
|
||
|
||
|
||
## 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).
|
||
|
||
### HistorianGateway
|
||
|
||
[Interactive HTML](mockups/HistorianGateway.html) · [Desktop PNG](evidence/HistorianGateway-desktop.png) · [Mobile PNG](evidence/HistorianGateway-mobile.png)
|
||
|
||

|
||
|