273 lines
31 KiB
Markdown
273 lines
31 KiB
Markdown
# ScadaBridge UI Consistency Implementation Plan
|
||
|
||
> **For Codex:** REQUIRED SUB-SKILL: Use `executeplan` to implement this plan task-by-task.
|
||
|
||
**Goal:** Adopt the Theme-first suite refinements in ScadaBridge while making operational status, audit filtering and modal workflows accessible and reliable.
|
||
|
||
**Architecture:** Keep CentralUI as a Razor class library hosted by ScadaBridge.Host and keep the existing authorization, data/query services and domain components. Shared tokens and additive component contracts arrive through G1 before local adoption. Pilot the documented dialog behavior using ScadaBridge's existing focus helpers; extract a generic component only after two consumers have demonstrated the contract.
|
||
|
||
**Tech Stack:** .NET 10, Blazor InteractiveServer, Bootstrap 5, shared Theme RCL, xUnit 2.9.3, bUnit 2.7.2 (`BunitContext` / `Render<T>`), NSubstitute; Python Playwright infrastructure already exists for browser smoke.
|
||
|
||
---
|
||
|
||
## 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, baseline and dependencies
|
||
|
||
- Source reviewed: `/Users/dohertj2/Desktop/ScadaBridge`; Theme **0.5.3** in `Directory.Packages.props`. Recheck HEAD/worktree status when executing: review `482ac665` → plan baseline `7e34d7c2`; intervening changes are `docker/Dockerfile` and `docker/build.sh` image-version stamping, with no UI diff. Leave those build scripts unchanged.
|
||
- Requirements: `/Users/dohertj2/Desktop/scadaproj/impeccable/ScadaBridge.md` findings SB-01–15 and shared design contract. Mockup fixtures show layout and interaction intent; sample site names, counts, changes and health values are not production requirements.
|
||
- **Dependency G1:** shared Theme compatibility audit, approved package artifact and version `THEME_VERSION`; semantic `--ok-ink:#236f34`, `--warn-ink:#855000`, `--bad-ink:#b42121`, `--idle-ink:#535d66`, `--ink-faint:#626970`; additive TechField `For/HintId/ErrorId`; additive shell `AccentDeep/AccentTint/AccentBorder/AccentFocus` retaining `Accent`; `--info-ink` independent of product accents, optional TechButton BusyText plus aria-busy, focus/reduced-motion rules, and table/filter/dialog recipes. Caller owns live outcomes. Never invent a numeric release version.
|
||
- Local correctness repairs and failing tests may progress once the shared contract is agreed; visual migration and package-dependent merges wait for G1. Keep blue product accent, rail, Plex, paper, domain state vocabulary, static login POST, anti-CSRF, audit attribution, live/replay gates, poll limits, failover safeguards and secured-write separation.
|
||
- ScadaBridge has an existing dark palette; retain dark mode and saved `sb-theme`. Do not replace it with a light-only prototype. A shared dark palette is adopted only if the Theme compatibility audit actually ships one; otherwise retain local dark token overrides and supply accessible dark semantic ink values with measured pairs.
|
||
- Plan only: no implementation, tests, service startup, NuGet publish or deployment is performed while writing this chapter. Use a suitable clean checkout/worktree when executing; record existing changes before edits.
|
||
|
||
## Execution notation and baseline commands
|
||
|
||
Every command below runs with cwd `/Users/dohertj2/Desktop/ScadaBridge` unless explicitly stated. Paths `U/…`, `H/…`, `T/…` in file inventories expand exactly to:
|
||
|
||
```text
|
||
U = src/ZB.MOM.WW.ScadaBridge.CentralUI
|
||
H = src/ZB.MOM.WW.ScadaBridge.Host
|
||
T = tests/ZB.MOM.WW.ScadaBridge.CentralUI.Tests
|
||
```
|
||
|
||
Set these task-specific shell variables once per execution shell (no production credentials):
|
||
|
||
```sh
|
||
SB_UI=src/ZB.MOM.WW.ScadaBridge.CentralUI
|
||
SB_TEST=tests/ZB.MOM.WW.ScadaBridge.CentralUI.Tests/ZB.MOM.WW.ScadaBridge.CentralUI.Tests.csproj
|
||
git status --short
|
||
dotnet test "$SB_TEST" -c Release
|
||
```
|
||
|
||
Expected post-GB baseline: tests pass. If an independent new failure appears after the recorded GB acceptance, investigate it before UI changes; do not treat it as a green baseline. A dependency/parser error is not the intended red test. Do not alter test package versions or suppressions as part of a visual task.
|
||
|
||
Each behavioral task follows: write the named regression; run its filter and observe the specific assertion fail; implement the smallest change; rerun filter; run related existing tests; commit only its named source/test files. bUnit proves state/markup, not physical keyboard trapping, contrast or browser layout. CSS-only changes use before/after screenshots and computed style checks rather than tests that mirror declarations. Proposed new files below are explicitly labelled create.
|
||
|
||
## Task SB-00: Compatibility adoption and baseline captures
|
||
|
||
**Files:** Modify `Directory.Packages.props`; inspect `U/ZB.MOM.WW.ScadaBridge.CentralUI.csproj`, `H/Components/App.razor`, `U/Components/Layout/MainLayout.razor`, `U/wwwroot/css/site.css`; create `docs/ui-consistency/ScadaBridge-verification.md` and `docs/ui-consistency/screenshots/` during implementation.
|
||
|
||
1. Record the prior package pin, screenshot route/role/scheme/viewport matrix and actual immutable G1 package digest/version. Run baseline tests above before bumping.
|
||
2. Capture login, dashboard, topology, health, audit, machine/instance editor and secured writes on a disposable authorized fixture at 1440×900, 768×1024, 390×844; repeat light/dark and 200% zoom. No deployed endpoint is assumed available; select the existing dev fixture during execution and record its URL instead of inventing a port.
|
||
3. Set only the Theme package version to the literal version supplied by G1. Resolve `.page-head` and button compatibility from computed behavior; keep local selectors until their replacement is verified.
|
||
4. Run `dotnet restore "$SB_TEST"` then `dotnet test "$SB_TEST" -c Release`; expected pass without changed business assertions. Capture mobile nav closed/open; page content must remain visible and rail footer reachable.
|
||
5. Commit: `git add Directory.Packages.props docs/ui-consistency/ScadaBridge-verification.md`; `git commit -m "chore(ui): adopt validated shared theme"`. Stage selected screenshot files explicitly if repository policy permits them.
|
||
|
||
## Task SB-01: Name reusable dialogs and prompt fields
|
||
|
||
**Maps:** report SB-01. **Depends:** SB-00/G1 overlay recipe.
|
||
**Files:** Modify `U/Components/Shared/DialogHost.razor`; extend `T/Shared/DialogHostShowAsyncTests.cs` and `T/Shared/DialogSeverityStylingTests.cs`.
|
||
|
||
1. Add `Dialog_HasVisibleTitleAsAccessibleName` to existing `DialogHostShowAsyncTests` using its real service and renderer. After opening the dialog, assert:
|
||
|
||
```csharp
|
||
var dialog = cut.Find("[role=dialog]");
|
||
var id = dialog.GetAttribute("aria-labelledby");
|
||
Assert.False(string.IsNullOrWhiteSpace(id));
|
||
Assert.Equal("Title", cut.Find("#" + id).TextContent.Trim());
|
||
```
|
||
|
||
Add prompt coverage asserting its label `for` identifies the input, and two successive dialogs do not leave stale ids/descriptions. Use existing `ShowAsync`/Prompt service signatures; no unawaited modal task may block test completion.
|
||
2. Run `dotnet test "$SB_TEST" --filter FullyQualifiedName~DialogHost`; expected red: missing title linkage/prompt association, then green after change.
|
||
3. Add unique title/body/prompt ids, `aria-labelledby`, appropriate `aria-describedby` and label/input linkage. Preserve current initial focus, Escape, result typing and confirmation severity.
|
||
4. Rerun filter plus `--filter FullyQualifiedName~DialogSeverityStylingTests`; browser announce title/body/input once and return focus on close.
|
||
5. Commit named files: `git commit -m "fix(ui): name ScadaBridge dialog controls"` after explicit `git add` of these three paths.
|
||
|
||
## Task SB-02: Pilot robust modal keyboard behavior in audit drawer
|
||
|
||
**Maps:** SB-02. **Depends:** SB-01 and G1 documented behavior; this is the first consumer pilot.
|
||
**Files:** Modify `U/Components/Audit/AuditDrilldownDrawer.razor`, `.razor.cs`, `U/wwwroot/js/dialog.js`, `U/Components/Shared/DialogHost.razor`; extend `T/Components/Audit/AuditDrilldownDrawerTests.cs`; create `infra/tools/ui_consistency_browser.py` and extend verification notes.
|
||
|
||
1. Add drawer test `OpenDrawer_HasNamedModalAndEscapeCloses`: reuse existing AuditEventView fixture, render IsOpen=true with OnClose spy, assert role/dialog name; send Escape and assert callback once. Red: no semantics/key handler. Run `dotnet test "$SB_TEST" --filter FullyQualifiedName~AuditDrilldownDrawerTests`.
|
||
2. Preserve the existing capture/restore helper intent. Replace delayed server-keydown reliance on `window.event` with an element-bound native DOM keydown listener that receives the actual event and calls `preventDefault()` synchronously at boundaries; ignore disabled, hidden and inert descendants. Provide cleanup; contain focus when no child is focusable; restore trigger only if still connected, otherwise focus the stable page heading.
|
||
3. Use the same lifecycle binding for DialogHost and audit drawer: capture before initial focus, activate once per opening, remove on close/dispose, lock background/scroll, restore once. Avoid a module-global single saved element if nested overlays are possible; keep per-instance state and intentional nesting policy. Do not mount a modal inside an animated transformed ancestor.
|
||
4. In new browser script use `playwright.sync_api` as the existing `infra/tools/playwright_smoke.py` does; accept explicit `--base-url`, `--storage-state`, `--output-dir`, do not embed credentials or auto-discover production. Test first/last Tab and Shift+Tab, hidden panels, Escape and disconnected-trigger fallback for confirm/prompt/drawer. Render-related unit tests cannot replace this.
|
||
5. Run the unit filter; then `python3 infra/tools/ui_consistency_browser.py --base-url "$SB_REVIEW_URL" --storage-state "$SB_REVIEW_STATE" --output-dir docs/ui-consistency/screenshots --case overlays` with paths supplied by the executor. Expected red on pre-change focus escaping, green after binding. No write operation is submitted; fixture drawer data is read-only.
|
||
6. Commit these explicit files with `git commit -m "fix(ui): preserve keyboard context in ScadaBridge overlays"`. Record pilot behavior for BTDB reuse; generic RCL extraction waits for its successful second pilot.
|
||
|
||
## Task SB-03: Wire labels, hints and errors across forms and filters
|
||
|
||
**Maps:** SB-03. **Depends:** SB-00 additive TechField contract.
|
||
**Files:** Modify `U/Components/Shared/DataTable.razor`, `MultiSelectDropdown.razor`, `U/Components/Audit/AuditFilterBar.razor`, `U/Components/Pages/Deployment/Topology.razor`, `FlowDebugger.razor`, `U/Components/Pages/Admin/Sites.razor`, `U/Components/Pages/Design/DataConnectionForm.razor`, `TemplateEdit.razor`; extend `T/DataConnectionFormTests.cs`, `T/Components/Audit/AuditFilterBarTests.cs`, `T/Deployment/FlowDebuggerPageTests.cs`; create `T/Shared/ControlLabelTests.cs`.
|
||
|
||
1. Add tests locating a visible label, reading `for`, and resolving exactly one input with that id; verify dropdown toggle accessible name includes Kind/Status/Site even after selection. For failed form submission assert error ids appear in that field's `aria-describedby` and `aria-invalid=true`; successful correction clears invalid state.
|
||
2. Run `dotnet test "$SB_TEST" --filter 'FullyQualifiedName~ControlLabelTests|FullyQualifiedName~DataConnectionFormTests|FullyQualifiedName~AuditFilterBarTests|FullyQualifiedName~FlowDebuggerPageTests'`; red: unnamed/unrelated fields, not CSS.
|
||
3. Add stable ids and visible labels. Use TechField `For/HintId/ErrorId` when replacing existing wrappers is minimal; callers still set input id and `aria-describedby`/`aria-invalid`. Add an optional `LabelledBy` parameter to local MultiSelectDropdown and pass label ids; do not replace domain editors.
|
||
4. Scan remaining route inventory for the same pattern in notification, SMTP/SMS, transport, instance and API forms; apply the same contract with their existing validation. Count all remaining unassociated fields in verification notes; resolve before family acceptance.
|
||
5. Rerun targeted tests and keyboard/forms-mode pass, including populated search, repeated editor rows and hidden panels. Commit explicit changed paths, `git commit -m "fix(ui): connect ScadaBridge field labels and errors"`.
|
||
|
||
## Task SB-04: Make audit custom windows explicitly UTC
|
||
|
||
**Maps:** SB-04. **Depends:** shared date-range recipe. **Decision:** retain the visible UTC contract and interpret custom picks as UTC; no new browser-zone conversion feature.
|
||
**Files:** Modify `U/Components/Audit/AuditFilterBar.razor.cs`, `.razor`; extend `T/Components/Audit/AuditFilterBarTests.cs`; inspect `U/Components/Shared/DateTimeRangeFilter.razor` without changing its input-only contract.
|
||
|
||
1. Add `CustomUtcWindow_IsIndependentOfHostLocalZone`: select Custom preset, set `audit-from/to` to `2026-11-12T10:00/11:00`, Apply, capture OnFilterChanged, assert FromUtc/ToUtc equal those instants with UTC kind; inputs stay 10:00/11:00 after rerender. Also assert inverted/invalid ranges do not emit a query and preserve text.
|
||
2. Run `TZ=America/Indianapolis dotnet test "$SB_TEST" --filter FullyQualifiedName~AuditFilterBarTests`; expected red: conversion shifts the 10:00 UTC input. Rerun under `TZ=UTC` and `TZ=Asia/Tokyo` after fix; each must produce identical UTC boundaries. These commands alter only process zone, not system settings.
|
||
3. Replace local `SpecifyKind(Local).ToUniversalTime()` with explicit UTC tagging of the timezone-free custom picks:
|
||
|
||
```csharp
|
||
private static DateTime? UtcInput(DateTime? value) =>
|
||
value.HasValue ? DateTime.SpecifyKind(value.Value, DateTimeKind.Utc) : null;
|
||
```
|
||
|
||
Apply it only to custom picks while building a query, and preserve the input values. Keep presets, UTC query storage and input-only component unchanged. Add concise pre-entry UTC guidance and appropriate validation links; adjust existing tests that asserted the old incorrect conversion.
|
||
4. Browser check browser/server differing zones and the DST transition dates 2026-03-08 / 2026-11-01: chosen UTC values must remain exact; do not interpret them as local ambiguous times. Audit exports/timestamp display retain their separately labelled contracts.
|
||
5. Commit the three files: `git commit -m "fix(audit): interpret labelled UTC windows consistently"` after explicit staging.
|
||
|
||
## Task SB-05: Preserve independent dashboard count states
|
||
|
||
**Maps:** SB-05. **Files:** Modify `U/Components/Pages/Dashboard.razor`; create `T/Pages/DashboardStateTests.cs` using existing NSubstitute/bUnit patterns and interfaces injected by Dashboard.
|
||
|
||
1. Create fixtures for ISiteRepository, ITemplateEngineRepository and IInboundApiKeyAdmin. `Counts_ApiFailureDoesNotRenderZeroOrEraseOtherCounts`: sites=2, connections=1, templates=3, API-key lookup throws; assert 2/1/3 still displayed, API keys says Unavailable, Retry is named. Add true zero, delayed load and retry-success cases.
|
||
2. Run `dotnet test "$SB_TEST" --filter FullyQualifiedName~DashboardStateTests`; expected red: API failure shows default zero. Do not infer count order from DOM indexes; identify each count by label or labelled region.
|
||
3. Give each count a nullable value plus loading/error status; load independently with individually caught failures, retain successful results, retry failed queries only. Introduce a tiny local helper only if useful, not a dashboard framework. Never treat unavailable as zero.
|
||
4. Rerun filter; browser confirms polite count state announcements without repeated polling chatter. Commit the two files with `git commit -m "fix(ui): separate dashboard counts from loading failures"`.
|
||
|
||
## Task SB-06: Name notification controls and retain recovery
|
||
|
||
**Maps:** SB-06. **Files:** Modify `U/Components/Shared/ToastNotification.razor`; extend `T/Shared/ToastNotificationTests.cs`.
|
||
|
||
1. Add `ToastDismiss_HasContextualName` using existing ShowError fixture; assert close button accessible label contains Dismiss and toast title; clicking removes only that toast. Run `dotnet test "$SB_TEST" --filter FullyQualifiedName~ToastNotificationTests`; expected red: missing name.
|
||
2. Set `aria-label="Dismiss [title]"`; preserve live-region behavior. Keep important save/query recovery inline in the initiating form; do not lengthen/disable every toast timer indiscriminately or claim toast history exists.
|
||
3. Rerun filter and screen-reader test with two notifications. Confirm focus is not forcibly moved on timed dismissal. Commit two files, `git commit -m "fix(ui): label ScadaBridge toast dismissal"`.
|
||
|
||
## Task SB-07: Adopt semantic text inks in light and dark
|
||
|
||
**Maps:** SB-07. **Depends:** SB-00/G1.
|
||
**Files:** Modify `U/wwwroot/css/site.css`, `U/Components/Pages/Deployment/FlowDebugger.razor.css`, `U/Components/Shared/FlowGraphView.razor.css`, `FlowTraceList.razor.css`, `U/Components/Layout/PendingUpdatesIndicator.razor`; update verification notes.
|
||
|
||
1. Capture actual computed caption/status/focus color pairs first. Record dark faint text failures; use no CSS-string unit tests.
|
||
2. Use shared `--*-ink` for text and keep saturated `--ok/--warn/--bad` for decorative dots/borders. Update local dark overrides with dark-readable semantic foregrounds; the G1 light #626970 faint token is not suitable unchanged on a dark surface. Retain existing dark surfaces and preference behavior.
|
||
3. Check normal text ≥4.5:1, large text/nontext controls/focus ≥3:1 across actual background pairs; include muted pending-update details and predicted/completed/failed/timeout/pending labels. Text state labels remain visible without color.
|
||
4. Run `dotnet test "$SB_TEST" -c Release --filter 'FullyQualifiedName~FlowDebuggerPageTests|FullyQualifiedName~PendingUpdatesHealthTilesTests'`; expected existing behavior stays green. Compare screenshots light/dark at mobile/desktop once.
|
||
5. Commit only these CSS/component/verification files with `git commit -m "style(ui): use shared readable semantic inks"`.
|
||
|
||
## Task SB-08: Standardize page and table hierarchy
|
||
|
||
**Maps:** SB-08. **Depends:** SB-00, SB-03.
|
||
**Files:** Modify `U/Components/Pages/Dashboard.razor`, `Deployment/Topology.razor`, `Admin/Sites.razor`, `Monitoring/Health.razor`, `U/Components/Shared/DataTable.razor`, `U/Components/Pages/Audit/ConfigurationAuditLog.razor`, plus family pages listed in verification notes; extend existing relevant page tests only for semantic heading behavior.
|
||
|
||
1. Add one heading assertion in `T/TopologyPageTests.cs`: exactly one h1 names Topology, no text/content loss. Run `dotnet test "$SB_TEST" --filter FullyQualifiedName~TopologyPageTests`; red before h1 change.
|
||
2. Adopt shared visual `.page-head` with semantic h1 (compact visual size), thin-rule headers and common action hierarchy. Replace `table-dark` with the shared light/dark token pattern; retain sorting/paging/table semantics. Put rare topology actions in a disclosure, keep task-primary action and search visible.
|
||
3. Migrate the same pattern through design/admin/deployment/monitoring/audit/notification/site-call families from the report inventory; avoid a separate title system for each. Preserve every existing action/role gate.
|
||
4. Use visual comparison rather than tests for spacing/border/font declarations. Run relevant page filters and check 200% zoom/wrapped actions. Commit explicit page files and tests, `git commit -m "style(ui): align ScadaBridge page and table anatomy"`.
|
||
|
||
## Task SB-09: Correct empty counts and contain table overflow
|
||
|
||
**Maps:** SB-09. **Files:** Modify `U/Components/Shared/DataTable.razor`; extend `T/Shared/DataTablePagerTests.cs`.
|
||
|
||
1. Add to the existing test class:
|
||
|
||
```csharp
|
||
[Fact]
|
||
public void EmptyTable_ShowsZeroItems()
|
||
{
|
||
var cut = RenderTable(itemCount: 0);
|
||
Assert.DoesNotContain("1–0", cut.Markup);
|
||
Assert.Contains("0 items", cut.Markup);
|
||
}
|
||
```
|
||
|
||
Also filter nonempty items to zero; retain first/last-page count tests. Add named region assertion only when the component renders its scroll wrapper.
|
||
2. Run `dotnet test "$SB_TEST" --filter FullyQualifiedName~DataTablePagerTests`; expected red: contradictory 1–0 count.
|
||
3. Render `0 items` for empty results; otherwise keep existing count/pager logic. Wrap overflow once with labelled region and keyboard access (avoid duplicate nested wrappers); add an optional table label parameter with safe default/callsite names.
|
||
4. Rerun filter. Browser test long identifiers at 390px/200%: document stays viewport width, table scrolls locally and controls remain reachable. Commit two files, `git commit -m "fix(ui): contain data tables and report empty counts"`.
|
||
|
||
## Task SB-10: Make dashboard destinations match authorization
|
||
|
||
**Maps:** SB-10. **Files:** Modify `U/Components/Pages/Dashboard.razor`; extend `T/Pages/DashboardStateTests.cs` created in SB-05; inspect policy use in `U/Components/Layout/NavMenu.razor`.
|
||
|
||
1. Parameterize role/policy fixtures using bUnit test authorization: Viewer cannot see Templates but can see configuration audit if OperationalAudit; Designer sees Templates; Deployer gets its permitted task links. Assert unauthorized links are absent and no policy is broadened.
|
||
2. Run `dotnet test "$SB_TEST" --filter FullyQualifiedName~DashboardStateTests`; red: current unconditional Templates link for Viewer.
|
||
3. Reuse the exact RequireDesign/OperationalAudit/etc. policies already applied by nav and routes. Do not infer permissions from a display string or change route authorization.
|
||
4. Rerun targeted tests; browser identities confirm rail/shortcut agreement. Commit two files, `git commit -m "fix(ui): align dashboard shortcuts with route policies"`.
|
||
|
||
## Task SB-11: Make operational summaries easier to scan
|
||
|
||
**Maps:** SB-11. **Depends:** SB-05/08/10.
|
||
**Files:** Modify `U/Components/Pages/Dashboard.razor`, `Monitoring/Health.razor`; preserve existing health tiles/services; extend `T/Pages/HealthPageTests.cs` only for ordering/freshness behavior.
|
||
|
||
1. Add behavior test with healthy/offline/error site fixtures: actionable exception appears before healthy entries, stable site ordering within each group; unavailable observation says Unknown, never Offline/Healthy by default. Run `dotnet test "$SB_TEST" --filter FullyQualifiedName~HealthPageTests`; expected red if current alphabetical order obscures the exception.
|
||
2. Replace equal-weight inventory tiles with compact shared facts strip; retain all configured counts and health drill-ins. Order existing site observations by actionable state then stable name/id; show last successful observation/freshness where existing data supplies it. No new aggregation service or invented live counter is required.
|
||
3. Verify loading/error/partial/true-zero states, current vs stale artifacts, and offline vs unknown distinctions. Keep failover controls/policies and active-error vs historical-count meanings.
|
||
4. Rerun HealthPageTests and `--filter FullyQualifiedName~HealthFailoverButtonTests`; visual check first viewport on tablet/desktop. Commit explicit files, `git commit -m "refactor(ui): prioritize actionable operational summaries"`.
|
||
|
||
## Task SB-12: Adapt topology density and scroll composition
|
||
|
||
**Maps:** SB-12. **Files:** Modify `U/Components/Pages/Deployment/Topology.razor`, `U/Components/Shared/TreeView.razor.css`, relevant local CSS in `U/wwwroot/css/site.css`; extend verification notes only for CSS behavior.
|
||
|
||
1. Capture short landscape/phone/200% zoom with loaded sites/areas and long names; record overflow or unusably short nested scroll region.
|
||
2. Replace guessed `100vh - 240px` with available-space grid/flex composition and dvh-compatible sizing; keep document scrolling viable on narrow screens. Add coarse-pointer hit-region sizing while preserving compact fine-pointer density and tree roving focus.
|
||
3. Preserve lazy branch loading, loaded-search qualification, selection persistence, poll gate and concurrency caps. No “search all sites” claim may be introduced without backend support.
|
||
4. Run `dotnet test "$SB_TEST" --filter 'FullyQualifiedName~TopologyPageTests|FullyQualifiedName~TopologyDisableConfirmLabelTests'`; expected existing behavioral tests remain green. Browser targets ≥44px practical touch hit height, no hidden focus, scroll operates at 390px/768px and short landscape.
|
||
5. Commit named layout files and verification notes, `git commit -m "style(ui): adapt topology to touch and short screens"`. Do not add CSS-declaration snapshot tests.
|
||
|
||
## Task SB-13: Reconcile theme palette ownership safely
|
||
|
||
**Maps:** SB-13. **Depends:** G1 compatibility decision, SB-07.
|
||
**Files:** Modify `U/wwwroot/css/site.css`, `U/Components/Layout/MainLayout.razor`, `U/Components/Shared/DarkModeToggle.razor`, `U/wwwroot/js/theme.js`, `H/Components/App.razor` only if preference migration is actually needed; extend verification notes.
|
||
|
||
1. Compare shipped G1 token list against local light/dark override keys. Record an ownership table. A light-only G1 release does not authorize deleting the local dark palette.
|
||
2. When a shared dark palette exists, remove duplicated values only after exact-pair screenshots pass. Preserve nonshared backdrop/domain colors. Use additive AccentDeep/Tint/Border/Focus consistently if passing Accent; avoid an inline light accent overriding a selected dark scheme.
|
||
3. Keep existing saved `sb-theme` readable and apply before paint. If G1 introduces a shared preference key, migrate old key once with blocked-storage fallback, and test both keys absent/present/conflicting; no preference reset.
|
||
4. Browser verify light/dark page, rail, Bootstrap controls, JSON/Monaco, overlays and first paint at desktop/mobile. Run `dotnet test "$SB_TEST" -c Release`; expected pass, no forced dark toggle scope change.
|
||
5. Commit only changed ownership/preference files and notes, `git commit -m "refactor(ui): reconcile ScadaBridge theme ownership"`.
|
||
|
||
## Task SB-14: Simplify audit filters and refuse invalid exact ids
|
||
|
||
**Maps:** SB-14. **Depends:** SB-03/04/08.
|
||
**Files:** Modify `U/Components/Audit/AuditFilterBar.razor`, `.razor.cs`, inspect `U/Components/Audit/AuditQueryModel.cs` (preserve its lax-parsing API for other callers); extend `T/Components/Audit/AuditFilterBarTests.cs`. Do not create a duplicate query model.
|
||
|
||
Minimal local guard before `_model.ToFilter(now)` (both exact-id fields):
|
||
|
||
```csharp
|
||
private static bool IsEmptyOrGuid(string text) =>
|
||
string.IsNullOrWhiteSpace(text) || Guid.TryParse(text, out _);
|
||
```
|
||
|
||
Keep `_model.ToFilter` semantics for other callers; the bar renders linked errors and returns before callback when either guard fails.
|
||
|
||
1. Add `MalformedExecutionId_DoesNotBroadenQuery`: type `not-a-guid`, Apply, assert no OnFilterChanged callback, input preserved, visible linked error. Cover parent id independently; whitespace-empty remains valid. Red before guard.
|
||
2. Add applied-filter tests: advanced Actor/Target constraints remain visible in summary when disclosure closes; Clear resets all advanced/common values and errors; channel changes still remove incompatible Kind selections. Run `dotnet test "$SB_TEST" --filter FullyQualifiedName~AuditFilterBarTests`.
|
||
3. Validate GUIDs/time ranges before constructing/emitting the filter, without changing repository semantics. Keep time/site/outcome/apply visible, put correlation/rare controls in More filters, retain active count and applied summary. Label pending vs applied state; a failed query must not imply new filters succeeded.
|
||
4. Preserve every existing filter and callback contract; update structure-only tests to locate new accessible containers rather than pinning old row count. Browser keyboard opens disclosure, invalid id is announced, applied hidden constraints remain recognizable.
|
||
5. Commit explicit changed component/test files with `git commit -m "fix(audit): keep precise filters visible and validated"`.
|
||
|
||
## Task SB-15: Consolidate domain status visuals and final acceptance
|
||
|
||
**Maps:** SB-15. **Depends:** all preceding tasks.
|
||
**Files:** Modify `U/Components/Pages/Deployment/FlowDebugger.razor.css`, `U/Components/Shared/FlowTraceList.razor.css`, `FlowGraphView.razor.css`, `U/Components/Audit/AuditEventDetail.razor.css`; verify `T/Deployment/FlowDebuggerPageTests.cs`, `FlowStepDetailTests.cs`, `FlowNodeLogPanelTests.cs`; update implementation verification notes.
|
||
|
||
1. Preserve Predicted/Live/Replay/Running/Pending/Parked/Completed/Timed out/Failed labels and mapping logic. Replace mixed Bootstrap/Theme text colors with shared semantic inks, thin surrounding rules and explicit message headings; remove thick decorative side bars.
|
||
2. Run `dotnet test "$SB_TEST" --filter 'FullyQualifiedName~FlowDebuggerPageTests|FullyQualifiedName~FlowStepDetailTests|FullyQualifiedName~FlowNodeLogPanelTests'`; no new test for CSS, existing semantic tests must remain green. Add a state-mapping test only if implementation changes mapping; include “error log on completed step remains completed.”
|
||
3. Run `dotnet test "$SB_TEST" -c Release`; run the new browser script overlay cases with fixture state and capture full matrix once. Inspect keyboard, zoom, reduced motion, real focus boundaries, noncolor status, copy/payload wrapping, stale/unknown/offline and role live/replay restrictions in the same batch.
|
||
4. Correct failures in one batch, confirm once; record limitations as named remaining gates, not claims that source tests proved browser correctness. Do not broaden to unrelated backend/package cleanup.
|
||
5. Commit named files plus verification notes, `git commit -m "style(ui): unify flow and audit state presentation"`.
|
||
|
||
## Findings coverage and release gates
|
||
|
||
| Report finding | Implementation task | Evidence needed |
|
||
|---|---|---|
|
||
| SB-01 dialog naming | SB-01 | bUnit title/prompt relationships + announced name |
|
||
| SB-02 audit drawer | SB-02 | real Tab/Escape/focus return; disposal |
|
||
| SB-03 field names | SB-03 | accessible control names/errors across families |
|
||
| SB-04 time windows | SB-04 | same UTC filter under three process/browser zones |
|
||
| SB-05 count failures | SB-05 | independent unavailable/zero/retry states |
|
||
| SB-06 toast controls | SB-06 | named dismiss; persistent inline recovery |
|
||
| SB-07 contrast | SB-07 | measured computed pairs both schemes |
|
||
| SB-08 page anatomy | SB-08 | one h1; shared table/action screenshots |
|
||
| SB-09 table count/overflow | SB-09 | empty result regression + local scrolling |
|
||
| SB-10 shortcut policy | SB-10 | role fixtures align nav/route/shortcut |
|
||
| SB-11 operational scan | SB-11 | actionable order, known vs unknown distinction |
|
||
| SB-12 touch/viewport | SB-12 | coarse-pointer/short viewport captures |
|
||
| SB-13 palette ownership | SB-13 | preference and both-scheme compatibility |
|
||
| SB-14 audit precision | SB-14 | no query on malformed GUID; visible applied constraints |
|
||
| SB-15 status consistency | SB-15 | domain semantics intact + shared palette |
|
||
|
||
**G2 consumer candidate:** all focused/full tests pass, package pin/digest recorded, all page families sampled after label scan, two schemes verified, overlay pilot documented for BTDB. No deployment is part of this plan-writing request. A later authorized deployment stages Theme package availability first, a disposable fixture, then one consumer instance/environment with normal deployment policy; never redeploy the SCADA fleet merely to inspect CSS.
|
||
|
||
**Rollback:** retain prior Theme pin and last known application artifact; revert local presentation/behavior commits together with dependent package pin if compatibility fails. Preserve data/schema, existing auth and audit semantics; this chapter introduces no migration. Dirty browser sessions must finish/cancel safely before app restart. If a new preference key was migrated, keep reading the old key during rollback rather than deleting user settings. Reproduce failure on fixture and record the gate before retrying rollout.
|