210 lines
16 KiB
Markdown
210 lines
16 KiB
Markdown
# SCADA Overview UI Consistency Implementation Plan
|
||
|
||
> **For Codex:** REQUIRED SUB-SKILL: Use `executeplan` to implement this plan task-by-task.
|
||
|
||
**Goal:** Make fleet health, freshness and diagnostic evidence readable and truthful within the shared Technical-Light system.
|
||
|
||
**Architecture:** Adopt the reviewed shared Theme release, then refine the existing snapshot-driven single page and instance widget. Preserve anonymous read-only operation, atomic snapshot adoption, active/leader distinctions and the separate meanings of gateway sessions and historian pool depth. No new probe path, authentication flow or shared domain abstraction is needed.
|
||
|
||
**Tech Stack:** .NET 10, Blazor InteractiveServer, Bootstrap CSS, ZB.MOM.WW.Theme, xUnit 2.9.3, bUnit 2.7.2 after GB (`BunitContext` / `Render`), existing fake TimeProvider.
|
||
|
||
---
|
||
|
||
## Required testing prerequisite
|
||
|
||
Complete [bUnit standardization](BUnit.md) and close **GB before any task in this chapter**, including local fixes and candidate UI pilots. All bUnit snippets below use the post-GB `BunitContext` / `Render` / `AddAuthorization` API; their inherited helpers must be migrated in GB. Preserve framework HtmlRenderer methods and xUnit runner APIs where used. Non-bUnit runtimes retain their existing harnesses, but their UI work also waits for the family gate. Old package pins are discovery baselines, not targets for this chapter.
|
||
|
||
## Scope, inputs and dependencies
|
||
|
||
- Repository containing this app: `/Users/dohertj2/Desktop/scadaproj`; app subtree `ZB.MOM.WW.Overview/`.
|
||
- Required inputs: `impeccable/Overview.md`, `impeccable/SHARED-DESIGN-SYSTEM.md`, `impeccable/mockups/Overview.html`; master plan and shared Theme chapter in this plan folder.
|
||
- Current Theme pin: `ZB.MOM.WW.Overview/src/ZB.MOM.WW.Overview/ZB.MOM.WW.Overview.csproj` → `0.5.0`. `THEME_VERSION` means the actual compatible release selected after G1, never a literal package version.
|
||
- G1 must supply accessible status ink, `--ink-faint`, complete accent family, focus/state/motion rules and recipes. Preserve Overview purple `#6d28d9`; obtain deep/tint/border/focus values from the approved shared accent configuration. Do not replace the app's accent with blue. Information-state blue remains independent.
|
||
- Work is implementation planning only. At execution, use the master plan's checkout/worktree policy; inspect existing changes before editing. Do not start an infrastructure stack or deploy from this chapter.
|
||
- All task commands below use cwd `/Users/dohertj2/Desktop/scadaproj/ZB.MOM.WW.Overview`. File paths are relative to that cwd unless explicitly prefixed. Perform numbered steps separately; a task is not one large shell script.
|
||
|
||
### Baseline and command contract
|
||
|
||
Run `git status --short` from the repository root; record unrelated edits. From the app cwd, run:
|
||
|
||
```sh
|
||
dotnet test tests/ZB.MOM.WW.Overview.Tests/ZB.MOM.WW.Overview.Tests.csproj
|
||
```
|
||
|
||
Expected: existing suite passes; record actual count and warnings. If restore/feed access or the existing bUnit/AngleSharp combination fails, record a baseline blocker and resolve separately; complete the required framework migration in GB before visual work; do not repeat incidental upgrades here. New tests extend the named existing test classes and reuse their `Card`, `Render`, `Node`, `Snapshot`, `RenderPage`, `_store`, `_time`, and `Now` helpers. Snippets below are methods inside those classes, with existing usings retained.
|
||
|
||
## OV-01 · Adopt shared ink and retain readable stale evidence
|
||
|
||
**Covers:** finding OV-01; DS-01, DS-03, DS-04, DS-06. **Depends:** G1.
|
||
|
||
**Modify:** `src/ZB.MOM.WW.Overview/ZB.MOM.WW.Overview.csproj`; `src/ZB.MOM.WW.Overview/Components/Layout/MainLayout.razor`; `src/ZB.MOM.WW.Overview/wwwroot/css/site.css`.
|
||
|
||
1. Change the Theme reference to the resolved `THEME_VERSION`; configure the approved purple deep/tint/border/focus values through the additive ThemeShell parameters. Build with `dotnet build src/ZB.MOM.WW.Overview/ZB.MOM.WW.Overview.csproj`; expected zero new warnings.
|
||
2. Remove `opacity:0.55` from stale instance body/host. Retain `.stale` state class and visible textual stale status. Migrate text uses of `--ok`, `--bad`, `--idle` to the shared `*-ink` tokens; retain signal tokens for squares/borders.
|
||
3. In a local test fixture with a five-minute-old healthy reading, visually inspect stale host, check details and old values. Measure computed foreground/background pairs including alpha; expected ≥4.5:1 for small essential text. Capture 1440px and 390px with 200% zoom and grayscale. Do not create a CSS-string assertion for the opacity change.
|
||
4. Run the complete app test command above. Existing `StaleCard_IsMarkedStaleButKeepsItsLastKnownStatusClass` and `PausedView_AgesIntoStaleOnItsOwn` must remain green.
|
||
5. From repo root stage only the three named files and commit `style(overview): adopt shared readable stale and status treatments`.
|
||
|
||
## OV-02 · Show every check's textual state
|
||
|
||
**Covers:** OV-02; DS-01, DS-05. **Depends:** OV-01.
|
||
|
||
**Modify:** `src/ZB.MOM.WW.Overview/Components/Widgets/InstanceCard.razor`; `tests/ZB.MOM.WW.Overview.Tests/InstanceCardTests.cs`.
|
||
|
||
1. Add this regression to `InstanceCardTests`:
|
||
|
||
```csharp
|
||
[Fact]
|
||
public void CheckRow_ExposesItsStatusWithoutInferringDescription()
|
||
{
|
||
var report = new ZbHealthReport
|
||
{
|
||
Status = "Degraded",
|
||
Entries = new Dictionary<string, ZbHealthEntry>
|
||
{
|
||
["database"] = new() { Status = "Degraded", Description = "slow response" }
|
||
}
|
||
};
|
||
var cut = Render(Card(report: report));
|
||
var row = cut.Find(".check-row");
|
||
Assert.Contains("Degraded", row.TextContent, StringComparison.Ordinal);
|
||
Assert.Equal("true", row.QuerySelector(".check-dot")!.GetAttribute("aria-hidden"));
|
||
}
|
||
```
|
||
|
||
2. Run `dotnet test tests/ZB.MOM.WW.Overview.Tests/ZB.MOM.WW.Overview.Tests.csproj --filter FullyQualifiedName~CheckRow_ExposesItsStatusWithoutInferringDescription`; expected FAIL because the status text/hidden decorative dot is absent.
|
||
3. Render an explicit text status beside name/description; use a neutral “Unknown” for absent/unrecognized values. Mark the square decorative. Preserve the actual remote description and its encoding; do not replace it with status copy.
|
||
4. Add cases Healthy/Unhealthy/null/unknown; run the same filter then `--filter FullyQualifiedName~InstanceCardTests`; expected PASS. Inspect accessibility-tree row reading order; VoiceOver testing is excluded by the user’s November14 instruction.
|
||
5. Stage the two named files; commit `fix(overview): expose each health check state in text`.
|
||
|
||
## OV-03 · Make pause describe display adoption
|
||
|
||
**Covers:** OV-03; DS-04. **Depends:** G1; independent of OV-02.
|
||
|
||
**Modify:** `src/ZB.MOM.WW.Overview/Components/Pages/Overview.razor`; `tests/ZB.MOM.WW.Overview.Tests/OverviewPageTests.cs`.
|
||
|
||
1. Add a behavior regression inside `OverviewPageTests`:
|
||
|
||
```csharp
|
||
[Fact]
|
||
public void Pause_IsAViewStateRatherThanADisconnection()
|
||
{
|
||
_store.Publish(Snapshot(Node("a", InstanceStatus.Up)));
|
||
var cut = RenderPage();
|
||
cut.Find("[data-testid=pause-toggle]").Click();
|
||
Assert.Equal("true", cut.Find("[data-testid=pause-toggle]").GetAttribute("aria-pressed"));
|
||
Assert.Contains("background polling continues", cut.Markup, StringComparison.OrdinalIgnoreCase);
|
||
Assert.Empty(cut.FindAll(".conn-pill[data-state=disconnected]"));
|
||
}
|
||
```
|
||
|
||
2. Run `dotnet test tests/ZB.MOM.WW.Overview.Tests/ZB.MOM.WW.Overview.Tests.csproj --filter FullyQualifiedName~Pause_IsAViewStateRatherThanADisconnection`; expected FAIL on missing pressed state.
|
||
3. Add `aria-pressed` and neutral “View paused — background polling continues” state. Keep `_paused` stopping adoption, keep independent UI age tick, and keep resume adopting `Store.Current`. Use a separate polite outcome region updated by pause/resume only, not on every sweep.
|
||
4. Run `dotnet test tests/ZB.MOM.WW.Overview.Tests/ZB.MOM.WW.Overview.Tests.csproj --filter FullyQualifiedName~OverviewPageTests`; expected PASS, including existing paused/adopt/resume/aging/disposal tests. Validate keyboard button activation and one announcement per toggle.
|
||
5. Stage the two named files; commit `fix(overview): distinguish paused view from connection failure`.
|
||
|
||
## OV-04 · Separate stale and unreachable group counts
|
||
|
||
**Covers:** OV-04; DS-05. **Depends:** GB; ship after OV-01.
|
||
|
||
**Modify:** `src/ZB.MOM.WW.Overview/Components/Pages/Overview.razor`; `tests/ZB.MOM.WW.Overview.Tests/OverviewPageTests.cs`.
|
||
|
||
1. Add the focused regression:
|
||
|
||
```csharp
|
||
[Fact]
|
||
public void GroupSummary_DoesNotCallAStaleHealthyNodeUnreachable()
|
||
{
|
||
_store.Publish(Snapshot(Node("a", InstanceStatus.Up, "site-a",
|
||
lastPolled: Now.AddMinutes(-5))));
|
||
var cut = RenderPage();
|
||
var text = cut.Find(".group-meta").TextContent;
|
||
Assert.Contains("1 stale", text, StringComparison.Ordinal);
|
||
Assert.Contains("0 unreachable", text, StringComparison.Ordinal);
|
||
}
|
||
```
|
||
|
||
2. Run `dotnet test tests/ZB.MOM.WW.Overview.Tests/ZB.MOM.WW.Overview.Tests.csproj --filter FullyQualifiedName~GroupSummary_DoesNotCallAStaleHealthyNodeUnreachable`; expected FAIL because stale is currently counted as unreachable.
|
||
3. Calculate unreachable count from stored reachability status, stale count from the render clock, and a union count only if a combined “affected” value is shown. Do not sum overlapping categories as a unique total. Qualify the app rollup when any contributing reading is stale; preserve last-known status rather than fabricating a fresh result.
|
||
4. Add matrix cases fresh unreachable, stale unreachable, mixed healthy/stale/down and initially pending. Run `dotnet test tests/ZB.MOM.WW.Overview.Tests/ZB.MOM.WW.Overview.Tests.csproj --filter FullyQualifiedName~OverviewPageTests`; expected PASS; confirm split-brain and leader labels unchanged.
|
||
5. Stage the two named files; commit `fix(overview): report freshness separately from reachability`.
|
||
|
||
## OV-05 · Make complete diagnostic errors available by disclosure
|
||
|
||
**Covers:** OV-05; DS-04, DS-05. **Depends:** G1 recipe.
|
||
|
||
**Modify:** `src/ZB.MOM.WW.Overview/Components/Widgets/InstanceCard.razor`; `src/ZB.MOM.WW.Overview/wwwroot/css/site.css`; `tests/ZB.MOM.WW.Overview.Tests/InstanceCardTests.cs`.
|
||
|
||
1. Add this regression inside `InstanceCardTests`:
|
||
|
||
```csharp
|
||
[Fact]
|
||
public void FullError_IsAvailableWithoutHover()
|
||
{
|
||
var error = "Probe failed: " + new string('x', 2000) + " diagnostic end";
|
||
var cut = Render(Card(InstanceStatus.Unreachable, error: error));
|
||
var disclosure = cut.Find("details[data-testid=instance-error]");
|
||
Assert.NotNull(disclosure.QuerySelector("summary"));
|
||
Assert.Contains(error, disclosure.TextContent, StringComparison.Ordinal);
|
||
}
|
||
```
|
||
|
||
2. Run `dotnet test tests/ZB.MOM.WW.Overview.Tests/ZB.MOM.WW.Overview.Tests.csproj --filter FullyQualifiedName~FullError_IsAvailableWithoutHover`; expected FAIL: no diagnostic disclosure.
|
||
3. Keep the compact error summary and add a native labelled disclosure containing full escaped text. Stack check name/status/description at narrow widths; constrain raw cluster-data scrolling to its own box. Preserve checks/native details and remote-data escaping before MarkupString.
|
||
4. Run the `InstanceCardTests` filter; expected PASS. At 1440/390px and 200% zoom inspect a long hostname, 2,000-character unbroken error, expanded checks and large raw cluster data. Enter/Space toggles the disclosure and focus stays visible; no body overflow.
|
||
5. Stage the three named files; commit `fix(overview): expose complete diagnostics on keyboard and touch`.
|
||
|
||
## OV-06 · Add optional exception focus and explicit UTC sweep time
|
||
|
||
**Covers:** OV-06; DS-03, DS-05. **Depends:** OV-01–05; preserve topology cards as default.
|
||
|
||
**Modify:** `src/ZB.MOM.WW.Overview/Components/Pages/Overview.razor`; `src/ZB.MOM.WW.Overview/wwwroot/css/site.css`; `tests/ZB.MOM.WW.Overview.Tests/OverviewPageTests.cs`.
|
||
|
||
1. Add a behavior test inside `OverviewPageTests`:
|
||
|
||
```csharp
|
||
[Fact]
|
||
public void NeedsAttentionFilter_KeepsStaleAndRestoresTheFullFleet()
|
||
{
|
||
_store.Publish(Snapshot(Node("fresh", InstanceStatus.Up),
|
||
Node("old", InstanceStatus.Up, lastPolled: Now.AddMinutes(-5)),
|
||
Node("down", InstanceStatus.Down)));
|
||
var cut = RenderPage();
|
||
cut.Find("input[data-testid=attention-filter]").Change(true);
|
||
Assert.Equal(2, cut.FindAll("[data-testid=instance-card]").Count);
|
||
cut.Find("input[data-testid=attention-filter]").Change(false);
|
||
Assert.Equal(3, cut.FindAll("[data-testid=instance-card]").Count);
|
||
Assert.Contains("UTC", cut.Find(".page-meta").TextContent, StringComparison.Ordinal);
|
||
}
|
||
```
|
||
|
||
2. Run `dotnet test tests/ZB.MOM.WW.Overview.Tests/ZB.MOM.WW.Overview.Tests.csproj --filter FullyQualifiedName~NeedsAttentionFilter_KeepsStaleAndRestoresTheFullFleet`; expected FAIL: filter absent.
|
||
3. Add a visible labelled checkbox “Needs attention”; default off. Filter on Down/Degraded/Unreachable/stale, with pending clearly labelled separately. Keep group/application identity and full-fleet summary truthful; report “no matching instances” with Clear when filtered empty. Show actual `GeneratedUtc` as explicit UTC using an invariant format; do not imply the server-local clock is the viewer's local time. Keep existing cards; the mockup's alternate compact view is optional future work, not required duplication.
|
||
4. Add initially pending/no-match/clear cases. Run the whole app test command; expected PASS. Inspect one synthetic large fleet before considering virtualization; record render cost without inventing a budget. Verify filter does not start probes, change ready/active reports or hide leader disagreement without a remaining group cue.
|
||
5. Stage the three named files; commit `feat(overview): add optional attention filter and explicit sweep zone`.
|
||
|
||
## OV-07 · Family acceptance and rollout record
|
||
|
||
**Covers:** all OV findings + DS-01–06 acceptance. **Create:** `docs/ui-consistency-validation.md` within `ZB.MOM.WW.Overview/`.
|
||
|
||
1. Run `dotnet build src/ZB.MOM.WW.Overview/ZB.MOM.WW.Overview.csproj -c Release`; expected zero new warnings.
|
||
2. Run `dotnet test tests/ZB.MOM.WW.Overview.Tests/ZB.MOM.WW.Overview.Tests.csproj -c Release`; expected all applicable tests pass; record count/SDK/package graph.
|
||
3. Render the real candidate UI with synthetic registry/snapshots at 1440px and 390px, 200% zoom, keyboard, automated accessibility-tree checks and reduced motion. VoiceOver testing is excluded by the user’s November14 instruction. Batch screenshots with sibling examples; inspect one pass and at most one corrective confirmation pass. Verify pending/empty/up/degraded/down/unreachable/stale/pause/resume/error/leader split and long data. No login or mutation control may appear.
|
||
4. Record actual Theme release, accent values, findings resolved, screenshots and any remaining runtime limits in the validation file; run Impeccable audit and polish after implementation. Reference mockups as proposed hierarchy, not baseline runtime proof.
|
||
5. Stage the validation file only; commit `docs(overview): record shared UI acceptance evidence`.
|
||
|
||
## Coverage matrix
|
||
|
||
| Review finding | Plan tasks | Shared dependencies |
|
||
|---|---|---|
|
||
| OV-01 stale opacity/faint text | OV-01, OV-07 | DS-01/03/04/06 |
|
||
| OV-02 check state only color | OV-02, OV-07 | DS-01/05 |
|
||
| OV-03 pause misleading | OV-03, OV-07 | DS-04 |
|
||
| OV-04 stale/unreachable conflation | OV-04, OV-07 | DS-05 |
|
||
| OV-05 hover-only errors/narrow checks | OV-05, OV-07 | DS-04/05 |
|
||
| OV-06 scale/zone | OV-06, OV-07 | DS-03/05 |
|
||
|
||
## Release and rollback
|
||
|
||
Overview is an app, not a NuGet package. Prepare a reviewed build and rollout record after all gates; deployment remains a separate explicitly authorized operation. Retain the previously built app artifact and exact Theme package graph. Roll back the app artifact/pin together if validation fails, retaining the same registry/data contracts. No database migration or shared runtime protocol change is planned. Keep the metadata/read-only and health-tier semantics unchanged throughout rollback.
|