Files
scadaproj/docs/plans/2026-11-12-scada-ui-consistency/Overview.md
T

16 KiB
Raw Blame History

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 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:

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:
[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"));
}
  1. 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.
  2. 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.
  3. Add cases Healthy/Unhealthy/null/unknown; run the same filter then --filter FullyQualifiedName~InstanceCardTests; expected PASS. Inspect a screen reader's row reading order.
  4. 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:
[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]"));
}
  1. 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.
  2. 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.
  3. 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.
  4. 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:
[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);
}
  1. 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.
  2. 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.
  3. 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.
  4. 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:
[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);
}
  1. Run dotnet test tests/ZB.MOM.WW.Overview.Tests/ZB.MOM.WW.Overview.Tests.csproj --filter FullyQualifiedName~FullError_IsAvailableWithoutHover; expected FAIL: no diagnostic disclosure.
  2. 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.
  3. 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.
  4. 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:
[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);
}
  1. Run dotnet test tests/ZB.MOM.WW.Overview.Tests/ZB.MOM.WW.Overview.Tests.csproj --filter FullyQualifiedName~NeedsAttentionFilter_KeepsStaleAndRestoresTheFullFleet; expected FAIL: filter absent.
  2. 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.
  3. 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.
  4. 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, screen reader and reduced motion. 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.