377 lines
37 KiB
Markdown
377 lines
37 KiB
Markdown
# OtOpcUa UI Consistency Implementation Plan
|
||
|
||
> **For Codex:** REQUIRED SUB-SKILL: Use `executeplan` to implement this plan task-by-task.
|
||
|
||
**Goal:** Apply one shared Technical-Light language to OtOpcUa's administration workflows while fixing accessible interaction, deployment feedback and task orientation.
|
||
|
||
**Architecture:** Adopt the reviewed Theme and Secrets UI releases, then change local page composition and interaction adapters without changing OPC UA, deployment, authorization or driver contracts. Preserve Raw virtualization/lazy loading, SSR authentication, per-page interactivity and bounded event tails. Shared recipes precede local pilots; generic behavior moves into Theme only after two consumers prove the same contract.
|
||
|
||
**Tech Stack:** .NET 10, Blazor SSR + per-page InteractiveServer, Bootstrap, ZB.MOM.WW.Theme/Secrets.Ui, xUnit v3, Shouldly and standard bUnit 2.7.2 after GB (`BunitContext` / `Render`), existing in-memory EF test fixtures.
|
||
|
||
---
|
||
|
||
## 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, versions and execution rules
|
||
|
||
- Cwd for all commands: `/Users/dohertj2/Desktop/OtOpcUa`. All file paths below are relative to this cwd. No production implementation is performed by writing this plan.
|
||
- Inputs: `/Users/dohertj2/Desktop/scadaproj/impeccable/OtOpcUa.md`, shared design-system recommendations, `mockups/OtOpcUa.html`, `mockups/OtOpcUa-Raw.html`, master plan and Theme G1.
|
||
- Scope: 31 routable components / 36 route templates / 32 page files including unrouted development sample. The Avalonia desktop client is excluded.
|
||
- Current central pins in `Directory.Packages.props`: Theme `0.5.0`, Secrets.Ui `0.6.2`. Use `THEME_VERSION` and `SECRETS_UI_VERSION` as planning placeholders only; resolve reviewed compatible releases at execution and commit actual values. No new release number is assumed.
|
||
- Required G1: semantic status text ink, enhanced TechField, complete accent family, focus/BusyText/aria-busy, reduced motion, table/filter/dialog recipes. OtOpcUa keeps the shared default blue. Preserve independent information-state blue and all operational status meanings.
|
||
- Required shared Secrets gate: target isolation and accessible shared UI verified in its chapter. Theme visual adoption waits for G1; local fixes may proceed independently only after GB closes.
|
||
- Preserve static SSR `Routes` for cookie login, static form POST/antiforgery, per-page interactive boundaries, Secrets wrapper route, server-side policies, existing URLs and protocol form JSON.
|
||
- Plan code snippets are regressions to add at execution, not executed test results. Existing source comments claiming “no bUnit” are stale: current project references bUnit and `Pages/DeleteConfirmRenderTests.cs` uses `BunitContext`. Complete GB first and use stable 2.7.2 APIs afterward; do not broaden the UI work into unrelated runner upgrades.
|
||
|
||
### Baseline / reusable commands
|
||
|
||
Inspect `git status --short` and actual HEAD. Then from this cwd:
|
||
|
||
```sh
|
||
dotnet build src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/ZB.MOM.WW.OtOpcUa.AdminUI.csproj
|
||
dotnet test tests/Server/ZB.MOM.WW.OtOpcUa.AdminUI.Tests/ZB.MOM.WW.OtOpcUa.AdminUI.Tests.csproj --filter Category=Unit
|
||
```
|
||
|
||
Expected existing baseline PASS/zero new warnings; record applicable counts. The full AdminUI suite includes explicit SQL integration prerequisites; do not infer their absence is a UI regression. At final gate run all tests that the documented test environment supports and identify skipped live/SQL requirements. Missing private-feed access, SDK or existing test-stack incompatibility is a baseline blocker, not a reason to alter unrelated packages. For each commit stage the listed task files only; preserve unrelated changes.
|
||
|
||
## OT-01 · Adopt shared API and label the first driver/filter surfaces
|
||
|
||
**Covers:** review OT-01; DS-01/02/04/06. **Depends:** G1 + shared Secrets candidate.
|
||
|
||
**Modify:** `Directory.Packages.props`; `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Shared/Drivers/DriverConfigModal.razor`; `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Shared/Drivers/Forms/CalculationDriverForm.razor`; `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Pages/ScriptLog.razor`; `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Pages/Uns/GlobalUns.razor`; `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Shared/ToastNotification.razor`.
|
||
**Create:** `tests/Server/ZB.MOM.WW.OtOpcUa.AdminUI.Tests/Pages/FormAccessibilityTests.cs`.
|
||
|
||
1. Add a `BunitContext` test class with `using Bunit`, `Microsoft.AspNetCore.Components`, `Microsoft.AspNetCore.Components.Forms`, `Shouldly`, `Xunit`, and `...AdminUI.Components.Shared.Drivers.Forms`. Add:
|
||
|
||
```csharp
|
||
[Fact]
|
||
[Trait("Category", "Unit")]
|
||
public void CalculationTimeout_HasAnAssociatedVisibleLabel()
|
||
{
|
||
var cut = Render<CascadingValue<EditContext>>(p => p
|
||
.Add(x => x.Value, new EditContext(new object()))
|
||
.AddChildContent<CalculationDriverForm>());
|
||
var input = cut.Find("input[type=number]");
|
||
input.Id.ShouldNotBeNullOrWhiteSpace();
|
||
cut.Find($"label[for='{input.Id}']").TextContent.ShouldContain("Run timeout");
|
||
}
|
||
```
|
||
|
||
2. Run `dotnet test tests/Server/ZB.MOM.WW.OtOpcUa.AdminUI.Tests/ZB.MOM.WW.OtOpcUa.AdminUI.Tests.csproj --filter FullyQualifiedName~CalculationTimeout_HasAnAssociatedVisibleLabel`; expected FAIL on missing association.
|
||
3. Set actual reviewed Theme/Secrets pins. Add stable unique control/hint/error IDs and enhanced TechField associations to the pilot/name field. Add visible labels for log level, script ID and loaded-UNS filter; add an accessible toast dismiss name. Use shared BusyText and caller outcome live regions only where meaningful. Retain protocol defaults/JSON semantics and masked credential fields.
|
||
4. Add invalid/error-description and two-form unique-ID cases, then run the FormAccessibilityTests filter; expected PASS. Verify actual labels in accessibility tree and label-click focus in a browser. Shared status text colors must use ink tokens while signal colors retain existing meaning.
|
||
5. Stage named files; commit `fix(admin-ui): adopt shared fields and label key filters`.
|
||
|
||
## OT-02 · Pilot accessible modal lifecycle on confirmations
|
||
|
||
**Covers:** OT-02; DS-04/05. **Depends:** G1 dialog recipe; cross-check with Secrets pilot.
|
||
|
||
**Modify:** `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Shared/Raw/RawConfirmDialog.razor`; `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/App.razor`; `tests/Server/ZB.MOM.WW.OtOpcUa.AdminUI.Tests/Pages/DeleteConfirmRenderTests.cs`.
|
||
**Create:** `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Shared/ModalFrame.razor`; `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/wwwroot/js/dialog-focus.js`; `tests/Server/ZB.MOM.WW.OtOpcUa.AdminUI.Tests/Pages/ModalAccessibilityTests.cs`.
|
||
|
||
1. In a new `ModalAccessibilityTests : BunitContext` with appropriate Raw component using, add:
|
||
|
||
```csharp
|
||
[Fact]
|
||
[Trait("Category", "Unit")]
|
||
public void ConfirmDialog_IsNamedAndCancelDoesNotInvokeDelete()
|
||
{
|
||
var deletes = 0;
|
||
var cut = Render<RawConfirmDialog>(p => p.Add(x => x.Visible, true)
|
||
.Add(x => x.Title, "Delete driver press-01")
|
||
.Add(x => x.Message, "Delete press-01? This cannot be undone.")
|
||
.Add(x => x.OnConfirm, () => deletes++));
|
||
var dialog = cut.Find("[role=dialog]");
|
||
dialog.GetAttribute("aria-modal").ShouldBe("true");
|
||
var id = dialog.GetAttribute("aria-labelledby");
|
||
id.ShouldNotBeNullOrWhiteSpace();
|
||
cut.Find($"[id='{id}']").TextContent.ShouldContain("press-01");
|
||
cut.Find(".modal-footer .btn-outline-secondary").Click();
|
||
deletes.ShouldBe(0);
|
||
}
|
||
```
|
||
|
||
2. Run `dotnet test tests/Server/ZB.MOM.WW.OtOpcUa.AdminUI.Tests/ZB.MOM.WW.OtOpcUa.AdminUI.Tests.csproj --filter FullyQualifiedName~ConfirmDialog_IsNamedAndCancelDoesNotInvokeDelete`; expected FAIL on modal name/state. Stub only documented module calls after adding DOM enhancement; do not make arbitrary JS calls pass.
|
||
3. Implement local ModalFrame per shared recipe, preserving existing Bootstrap shell selectors where tests/users depend on them. Supply title/description IDs, initial safe focus, tab containment, background inert state, Escape/close rules and focus return. Pass actual DOM event to handlers, never `window.event`; dispose listeners and restore prior background state. Preserve busy deletion and prevent close from suggesting an in-flight delete was undone.
|
||
4. Run ModalAccessibilityTests and DeleteConfirmRenderTests filters; expected PASS including actual deletion only after confirmation. Browser-test Tab/Shift-Tab/Escape/open/cancel/success with trigger removed and 390px scroll. bUnit does not validate native focus isolation.
|
||
5. Stage task files only; commit `fix(admin-ui): apply accessible confirmation focus lifecycle`.
|
||
|
||
## OT-03 · Name tree controls without sacrificing virtualization
|
||
|
||
**Covers:** OT-03; DS-04/05. **Depends:** G1 control pattern.
|
||
|
||
**Modify:** `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Shared/Uns/UnsTree.razor`; `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Shared/Raw/RawTree.razor`.
|
||
**Create:** `tests/Server/ZB.MOM.WW.OtOpcUa.AdminUI.Tests/Pages/TreeAccessibilityTests.cs`.
|
||
**Preserve tests:** `tests/Server/ZB.MOM.WW.OtOpcUa.AdminUI.Tests/Raw/RawTreeRowsTests.cs`.
|
||
|
||
1. Add a `TreeAccessibilityTests : BunitContext` with UnsTree/UnsNode usings:
|
||
|
||
```csharp
|
||
[Fact]
|
||
[Trait("Category", "Unit")]
|
||
public void UnsBranch_ExposesItsNodeNameAndExpansionState()
|
||
{
|
||
var node = new UnsNode { Kind = UnsNodeKind.Equipment, Key = "eq:1",
|
||
DisplayName = "press-01", HasLazyChildren = true, Expanded = false };
|
||
var cut = Render<UnsTree>(p => p.Add(x => x.Roots, new[] { node }));
|
||
var button = cut.Find("button[aria-expanded]");
|
||
button.GetAttribute("aria-expanded").ShouldBe("false");
|
||
button.GetAttribute("aria-label")!.ShouldContain("press-01");
|
||
node.Expanded = true;
|
||
cut.Render();
|
||
cut.Find("button[aria-expanded]").GetAttribute("aria-expanded").ShouldBe("true");
|
||
}
|
||
```
|
||
|
||
2. Run `dotnet test tests/Server/ZB.MOM.WW.OtOpcUa.AdminUI.Tests/ZB.MOM.WW.OtOpcUa.AdminUI.Tests.csproj --filter FullyQualifiedName~UnsBranch_ExposesItsNodeNameAndExpansionState`; expected FAIL: no state attribute.
|
||
3. Add node-specific toggle names and real expansion state to both trees, plus tag-named selection checkboxes. Use semantic nested/list or grouped structures; do not add incomplete ARIA tree roles. Retain Raw flattening, lazy child loading, Show more and stable keys; do not substitute the nonvirtualized shared TreeTable.
|
||
4. Add filtered-path expansion, lazy-load error, leaf-with-no-expansion and picker checkbox-name cases. Run TreeAccessibilityTests and RawTreeRowsTests filters; expected PASS. Browser-test focus after refresh/Show more and keyboard expansion on large branches.
|
||
5. Stage modified trees/new test; commit `fix(admin-ui): expose tree node labels and expansion state`.
|
||
|
||
## OT-04 · Replace placeholder home with role-appropriate task orientation
|
||
|
||
**Covers:** OT-04; DS-05. **Depends:** OT-05 navigation taxonomy.
|
||
|
||
**Modify:** `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Pages/Home.razor`.
|
||
|
||
1. Record current home at Viewer/Operator, Designer and Administrator roles; confirm the “nav above” placeholder and choose the shared compact page-header pattern. This is content/layout work: no test duplicating link text is required.
|
||
2. Replace the placeholder with concise task orientation linking Fleet/Hosts for inspection, Raw/UNS for policy-authorized authoring and Deployments for ConfigEditor. Do not invent an aggregate endpoint, live metric, pending-change count or environment label not supplied by source. Existing pages remain the source of runtime evidence.
|
||
3. Use one h1 and accurate wording about the side navigation and next-deployment application. Keep browser title product-qualified and expose a clearly labelled way to return to fleet status.
|
||
4. Build the AdminUI project using the baseline build command; expected zero new warnings. Browser-check the three role cases; unavailable operations must not appear as dead-end actions. At 390px/zoom the first useful task remains visible without opening multiple disclosures.
|
||
5. Stage Home only; commit `feat(admin-ui): orient the landing page around existing operator tasks`.
|
||
|
||
## OT-05 · Group navigation and retire ordinary Namespace links
|
||
|
||
**Covers:** OT-05; DS-05/06. **Depends:** G1; retain authorization policies unchanged.
|
||
|
||
**Modify:** `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Layout/MainLayout.razor`; `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Shared/ClusterNav.razor`; `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Pages/Clusters/ClusterNamespaces.razor`; `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Pages/Clusters/NamespaceEdit.razor`; `tests/Server/ZB.MOM.WW.OtOpcUa.AdminUI.Tests/SecretsNavLinkTests.cs`.
|
||
**Create:** `tests/Server/ZB.MOM.WW.OtOpcUa.AdminUI.Tests/Pages/NavigationPolicyRenderTests.cs`.
|
||
|
||
1. Add bUnit rendered policy cases using `Bunit.TestDoubles`, existing `AddAuthorization`, and `AdminUiPolicies` from `ZB.MOM.WW.OtOpcUa.Security.Auth`. In `NavigationPolicyRenderTests : BunitContext`, add:
|
||
|
||
```csharp
|
||
[Fact]
|
||
[Trait("Category", "Unit")]
|
||
public void AuthenticatedReader_IsNotOfferedFleetAdminPages()
|
||
{
|
||
var auth = this.AddAuthorization();
|
||
auth.SetAuthorized("viewer");
|
||
auth.SetPolicies(AdminUiPolicies.AuthenticatedRead);
|
||
var cut = Render<ZB.MOM.WW.OtOpcUa.AdminUI.Components.Layout.MainLayout>();
|
||
cut.FindAll("a[href='/role-grants'],a[href='/apikeys']").ShouldBeEmpty();
|
||
cut.Find("a[href='/fleet']").ShouldNotBeNull();
|
||
}
|
||
```
|
||
|
||
2. Run `dotnet test tests/Server/ZB.MOM.WW.OtOpcUa.AdminUI.Tests/ZB.MOM.WW.OtOpcUa.AdminUI.Tests.csproj --filter FullyQualifiedName~AuthenticatedReader_IsNotOfferedFleetAdminPages`; expected FAIL: currently advertised admin links.
|
||
3. Group real routes into Operations, Configuration, Scripting and Administration using shared nav sections; use ScrollNav only after actual adopted package supports it. Gate each restricted link by the exact page policy constant, including shared Secrets policy. Hide retired Namespace tab while retaining its compatibility URLs; replace route-name prose with working Raw/UNS links. Do not hide read-only routes simply because they live near editing routes.
|
||
4. Add Designer/Administrator/Secrets-policy cases, current-location checks, and compatibility-page links. Update the old source guard to identify the Secrets-specific AuthorizeView rather than assuming it is the first gate. Run the two navigation test filters plus PageAuthorizationGuardTests; expected PASS. Browser-test short viewport footer/scroll behavior and retained deep links.
|
||
5. Stage named files; commit `fix(admin-ui): align navigation groups and visibility with page policies`.
|
||
|
||
## OT-06 · Standardize page/table grammar across routes
|
||
|
||
**Covers:** OT-06; DS-05. **Depends:** G1; OT-01 and OT-05.
|
||
|
||
**Modify first:** `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Pages/Fleet.razor`; `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Pages/Deployments.razor`; `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Pages/Scripts.razor`; `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Pages/Uns/EquipmentPage.razor`, all under the same `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI` root.
|
||
|
||
**Then apply the same recipe to exact remaining page files under that root:** `Components/Pages/Account.razor`, `AlarmsHistorian.razor`, `Alerts.razor`, `ApiKeys.razor`, `Certificates.razor`, `FleetDiagnostics.razor`, `Hosts.razor`, `Reservations.razor`, `RoleGrants.razor`, `ScriptEdit.razor`, `ScriptLog.razor`, `Raw/GlobalRaw.razor`, `Uns/GlobalUns.razor`, and `Clusters/AclEdit.razor`, `ClusterAcls.razor`, `ClusterAudit.razor`, `ClusterEdit.razor`, `ClusterNamespaces.razor`, `ClusterOverview.razor`, `ClusterRedundancy.razor`, `ClustersList.razor`, `NamespaceEdit.razor`, `NewCluster.razor`, `NodeEdit.razor`. Home is OT-04; Login already has a primary heading; Secrets heading is library-owned.
|
||
|
||
1. Inspect Fleet vs Deployments screenshots and document the target shared h1/description/actions/table grammar. No unit test asserting font size, CSS class or literal header markup is needed for this reversible style change.
|
||
2. Convert the first four pages: semantic h1 at the shared compact size, section h2, product-qualified PageTitle, labelled scoped table scroll regions, correct header scope/action context. Preserve tab/button keyboard semantics in Equipment; do not turn routed cluster links into a partial ARIA tab widget.
|
||
3. Repeat the same edit/visual-check sequence in small batches: runtime pages; security/admin pages; cluster authoring/detail pages. Commit each batch separately with its exact changed paths; do not one-shot rewrite all 31 components. Compare declarations before trimming copied CSS.
|
||
4. Build using the baseline command after each batch; expected zero new warnings. Verify actual route titles/headings at 1440/390px and keyboard region scroll. Existing bUnit deletion/serialization suites remain green; add behavioral tests only where semantics such as active tabs or accessible action context change.
|
||
5. Commit batch messages `style(admin-ui): standardize runtime page and table anatomy`, then analogous admin/cluster messages. Record route coverage in OT-13 validation document.
|
||
|
||
## OT-07 · Make toolbars and dense trees usable on narrow/touch layouts
|
||
|
||
**Covers:** OT-07; DS-04/05. **Depends:** OT-03/06.
|
||
|
||
**Modify:** `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/wwwroot/css/site.css`; `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Pages/ScriptLog.razor`; `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Pages/FleetDiagnostics.razor`; `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Shared/ContextMenu.razor.css`; `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Shared/Raw/RawTree.razor`.
|
||
|
||
1. Capture 390px and 200% zoom with long labels; identify actual overflow in log filters, diagnostics controls and Raw rows. Test rendered boxes rather than adding CSS-token assertions.
|
||
2. Use shared wrapping toolbars, flexible min-width-zero fields and stacked page actions; constrain tables to their own labelled scroll containers. Increase coarse-pointer hit area toward 44px while retaining efficient desktop density; evaluate 24px AA target/spacing requirements separately.
|
||
3. If Raw row height changes on touch, update Virtualize ItemSize consistently with the rendered row strategy; do not retain a 30px estimate for 44px rows. Keep focus and stable-key identity when breakpoint/density changes.
|
||
4. Run the baseline build and RawTreeRowsTests filter; expected PASS. Browser-check pointer hitboxes, tree toggle/menu adjacency, no body overflow, scrolled table keyboard access and long-depth branches. Use the shared desktop/mobile snapshot batch, not repeated unbounded polishing.
|
||
5. Stage listed changed files; commit `fix(admin-ui): adapt dense toolbars and tree targets to touch layouts`.
|
||
|
||
## OT-08 · Expose full errors and audit details without hover
|
||
|
||
**Covers:** OT-08; DS-04/05. **Depends:** shared details recipe.
|
||
|
||
**Create:** `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Shared/DiagnosticDetails.razor`; `tests/Server/ZB.MOM.WW.OtOpcUa.AdminUI.Tests/Pages/DiagnosticDetailsTests.cs`.
|
||
**Modify:** `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Pages/Fleet.razor`, `Deployments.razor`, `ScriptLog.razor`, `AlarmsHistorian.razor`, `Clusters/ClusterAudit.razor` (all relative to the same page root).
|
||
|
||
1. Add a `DiagnosticDetailsTests : BunitContext` regression for the new presentation-only component (`Summary` and `Text` string parameters):
|
||
|
||
```csharp
|
||
[Fact]
|
||
[Trait("Category", "Unit")]
|
||
public void FullDiagnostic_IsAvailableToKeyboardAndIsEscaped()
|
||
{
|
||
var text = "<script>bad()</script>" + new string('x', 2000);
|
||
var cut = Render<DiagnosticDetails>(p => p
|
||
.Add(x => x.Summary, "Failure reason").Add(x => x.Text, text));
|
||
cut.Find("details summary").TextContent.ShouldContain("Failure reason");
|
||
cut.Find("details").TextContent.ShouldContain(text);
|
||
cut.FindAll("script").ShouldBeEmpty();
|
||
}
|
||
```
|
||
|
||
2. Run `dotnet test tests/Server/ZB.MOM.WW.OtOpcUa.AdminUI.Tests/ZB.MOM.WW.OtOpcUa.AdminUI.Tests.csproj --filter FullyQualifiedName~DiagnosticDetailsTests`; expected initial compile FAIL because component is new.
|
||
3. Implement a native disclosure using Razor-escaped full text, wrapping/scoped payload scroll and compact summary. Use it at each hover-only critical detail; include exact timestamp/correlation when available and existing node diagnostics links. Do not read whole deployment artifact blobs to obtain error metadata. Native selection supports copying; an extra Copy button is unnecessary unless it adds a measured benefit.
|
||
4. Rerun the focused test; expected PASS. Browser-test touch/keyboard disclosure, long unbroken error, JSON and absent payload. Confirm focus and full diagnostic content without `title` hover, and compare visual grammar with Overview's error disclosure.
|
||
5. Stage task files; commit `fix(admin-ui): make complete diagnostics available without hover`.
|
||
|
||
## OT-09 · Distinguish request acceptance and deployment application
|
||
|
||
**Covers:** OT-09; DS-04/05. **Depends:** OT-06/08.
|
||
|
||
**Modify:** `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Pages/Deployments.razor`.
|
||
**Create:** `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Shared/DeploymentFeedback.razor`; `tests/Server/ZB.MOM.WW.OtOpcUa.AdminUI.Tests/Pages/DeploymentFeedbackTests.cs`.
|
||
**Reuse:** `tests/Server/ZB.MOM.WW.OtOpcUa.AdminUI.Tests/Api/DeploymentStatusEndpointTests.cs`; existing DeploymentDriftProbe tests.
|
||
|
||
1. Add a `DeploymentFeedbackTests : BunitContext` regression using `DeploymentStatus` from Configuration.Enums. New component is presentation only, with `RequestAccepted`, nullable `Status`, `FailureReason`, `InitialLoading` parameters:
|
||
|
||
```csharp
|
||
[Fact]
|
||
[Trait("Category", "Unit")]
|
||
public void AcceptedRequest_IsNotPresentedAsCompletedApplication()
|
||
{
|
||
var cut = Render<DeploymentFeedback>(p => p.Add(x => x.RequestAccepted, true)
|
||
.Add(x => x.Status, DeploymentStatus.AwaitingApplyAcks));
|
||
cut.Find("[role=status]").TextContent.ShouldContain("in progress");
|
||
cut.Find("[role=status]").TextContent.ShouldNotContain("completed");
|
||
}
|
||
```
|
||
|
||
2. Run `dotnet test tests/Server/ZB.MOM.WW.OtOpcUa.AdminUI.Tests/ZB.MOM.WW.OtOpcUa.AdminUI.Tests.csproj --filter FullyQualifiedName~DeploymentFeedbackTests`; expected initial compile FAIL because component is new.
|
||
3. Implement honest loading/no-history/accepted/in-flight/sealed/sealed-degraded/rejected/no-change/failure feedback. Keep accepted copy “Request accepted — deployment in progress”; expose the current request and an explicit Refresh action with last-fetched time. Manual refresh satisfies the review without introducing new polling. Preserve scalar 50-row query, current deployment/NodeDeploymentState meaning, ConfigEditor policy and pending-operation disabling. NoChanges is informational; no terminal success is fabricated.
|
||
4. Add tests for each real enum (`Dispatching`, `AwaitingApplyAcks`, `Sealed`, `PartiallyFailed`, `TimedOut`), sealed with reason, initial pending vs empty, and no-change. Run focused test plus DeploymentStatusEndpointTests and DeploymentDriftProbeTests filters; expected PASS. Browser-submit a synthetic candidate only in an authorized isolated fixture; verify page reload is not needed to request status refresh and per-node detail links remain visible.
|
||
5. Stage new presentation/test and page files; commit `fix(admin-ui): separate accepted deployments from application outcomes`.
|
||
|
||
## OT-10 · Explain loaded-tree filtering and provide root retry
|
||
|
||
**Covers:** OT-10; DS-04/05. **Depends:** OT-01/03.
|
||
|
||
**Modify:** `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Pages/Raw/GlobalRaw.razor`; `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Pages/Uns/GlobalUns.razor`; `tests/Server/ZB.MOM.WW.OtOpcUa.AdminUI.Tests/Raw/FakeRawTreeService.cs`.
|
||
**Create:** `tests/Server/ZB.MOM.WW.OtOpcUa.AdminUI.Tests/Pages/TreeRecoveryTests.cs`.
|
||
|
||
1. Add an optional fake `Func<CancellationToken,Task<IReadOnlyList<RawNode>>> LoadRootsOverride` and delegate LoadRootsAsync to it when supplied, preserving throw-by-default behavior. Add a BunitContext regression (usings for Raw fake, page and Uns service types):
|
||
|
||
```csharp
|
||
[Fact]
|
||
[Trait("Category", "Unit")]
|
||
public void RootFailure_CanBeRetriedWithoutBecomingFalseEmptyData()
|
||
{
|
||
var attempts = 0;
|
||
var svc = new FakeRawTreeService { LoadRootsOverride = _ =>
|
||
++attempts == 1
|
||
? Task.FromException<IReadOnlyList<RawNode>>(new IOException("synthetic outage"))
|
||
: Task.FromResult<IReadOnlyList<RawNode>>(Array.Empty<RawNode>()) };
|
||
Services.AddSingleton<IRawTreeService>(svc);
|
||
var cut = Render<GlobalRaw>();
|
||
cut.Find("[data-testid=raw-retry]").Click();
|
||
cut.WaitForAssertion(() => attempts.ShouldBe(2));
|
||
cut.Markup.ShouldContain("No clusters");
|
||
}
|
||
```
|
||
|
||
2. Run `dotnet test tests/Server/ZB.MOM.WW.OtOpcUa.AdminUI.Tests/ZB.MOM.WW.OtOpcUa.AdminUI.Tests.csproj --filter FullyQualifiedName~TreeRecoveryTests`; expected FAIL: Retry absent.
|
||
3. Add local root loading/error/retry branches and a role-appropriate no-cluster next step. Label UNS “Filter loaded items” and explain unloaded tag scope; show separate no matches and Clear. Do not claim whole-tree/global search or add an endpoint. Retain no-prerender Raw tree behavior and lazy loading.
|
||
4. Add a second attempt failure, retry reentry prevention and UNS clear/no-matches tests; run focused filter + existing RawTreeRowsTests, expected PASS. Browser-test returning focus to filter/Retry, no fake zero counts and no search of unloaded data implied.
|
||
5. Stage listed files; commit `fix(admin-ui): clarify tree filter scope and recover failed root loads`.
|
||
|
||
## OT-11 · Add readable live-tail pause and stale refresh outcomes
|
||
|
||
**Covers:** OT-11; DS-04/05. **Depends:** OT-01/08/09.
|
||
|
||
**Modify:** `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Pages/ScriptLog.razor`; `Alerts.razor`, `Fleet.razor`, `Hosts.razor` under the same page root; `tests/Server/ZB.MOM.WW.OtOpcUa.AdminUI.Tests/LiveTail/LiveTailTests.cs`.
|
||
**Create:** `tests/Server/ZB.MOM.WW.OtOpcUa.AdminUI.Tests/Pages/LiveTailPageTests.cs`.
|
||
|
||
1. Add a page regression using the existing broadcaster and current bUnit API; new test class imports Bunit, DI, Shouldly, Xunit, Hubs, Pages and Commons.Messages.Logging:
|
||
|
||
```csharp
|
||
[Fact]
|
||
[Trait("Category", "Unit")]
|
||
public void PausedLog_KeepsReadingStableThenResumesLatestBoundedTail()
|
||
{
|
||
var feed = new InProcessBroadcaster<ScriptLogEntry>();
|
||
Services.AddSingleton<IInProcessBroadcaster<ScriptLogEntry>>(feed);
|
||
var cut = Render<ScriptLog>();
|
||
cut.Find("[data-testid=tail-pause]").Click();
|
||
feed.Publish(new ScriptLogEntry("script-a", "Information", "new sample",
|
||
DateTime.UtcNow, null, null, null));
|
||
cut.WaitForAssertion(() => cut.Find("[data-testid=tail-retained-count]")
|
||
.TextContent.ShouldBe("1"));
|
||
cut.FindAll("tbody").Any(x => x.TextContent.Contains("new sample")).ShouldBeFalse();
|
||
cut.Find("[data-testid=tail-pause]").Click();
|
||
cut.WaitForAssertion(() => cut.Markup.ShouldContain("new sample"));
|
||
}
|
||
```
|
||
|
||
2. Run `dotnet test tests/Server/ZB.MOM.WW.OtOpcUa.AdminUI.Tests/ZB.MOM.WW.OtOpcUa.AdminUI.Tests.csproj --filter FullyQualifiedName~LiveTailPageTests`; expected FAIL: pause/retained feedback absent. Wait on retained-count after scheduler flush so the test cannot pass before event processing.
|
||
3. Freeze the displayed snapshot while the bounded buffer continues retaining/coalescing; show visible pending/retained count, `aria-pressed` and Resume. Resume adopts latest retained rows; Clear visible log clears retained/pending/display state without implying deleting historian records. Announce connection changes/pause/error once, never every row. For Fleet/Hosts refresh failure preserve the last successful reading plus stale/error time rather than replace all context with a boundary; retain original overlap/cancellation/disposal guards.
|
||
4. Add burst-over-capacity/pause-clear/resume/disconnect/dispose tests, extending existing live-tail tests rather than replacing them. Run LiveTailPageTests/LiveTailTests/InProcessBroadcasterTests filters and baseline Unit suite; expected PASS. Browser-check stable scroll/focus while paused, retained capacity 500, honest disconnect vs no events, and retryable stale Fleet data.
|
||
5. Stage exact task files; commit `feat(admin-ui): support stable live-tail reading and honest stale refresh state`.
|
||
|
||
## OT-12 · Normalize icons and status aliases after behavioral fixes
|
||
|
||
**Covers:** OT-12; DS-01/05. **Depends:** G1, OT-03/06.
|
||
|
||
**Modify:** `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Shared/Raw/RawTree.razor`; `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Shared/Uns/UnsTree.razor`; `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/wwwroot/css/site.css`; local chip call sites `Components/Pages/Alerts.razor`, `ScriptLog.razor`, `Fleet.razor`, `Hosts.razor`, `AlarmsHistorian.razor`, `RoleGrants.razor`, and `Components/Shared/Uns/ImportEquipmentModal.razor` under that same UI root.
|
||
|
||
1. Compare OS-dependent emoji/current aliases with the family-approved icon treatment. No unit test asserting SVG paths, colors or icon counts is needed.
|
||
2. Replace platform emoji with the one shared icon set or authored simple SVG controls; retain text names and hide decorative icons. Do not fetch an external icon CDN. Reuse OT-03 control labels.
|
||
3. Migrate chip-alert/chip-caution to canonical semantic status components/classes after comparing actual adopted release, then remove only now-unused aliases. Keep degraded distinct from healthy, disabled distinct from failed, connection distinct from node health.
|
||
4. Run baseline build and TreeAccessibilityTests/RawTreeRowsTests filters; expected PASS. Inspect Linux/Windows/macOS rendering evidence where available, small labels, warning/bad contrast and long tree rows. This is consistency polish after behavior, not a parallel visual redesign.
|
||
5. Stage exactly changed call sites/CSS; commit `style(admin-ui): align technical icons and canonical status treatments`.
|
||
|
||
## OT-13 · Roll field associations through every protocol family
|
||
|
||
**Covers:** completes OT-01; DS-02. **Depends:** OT-01 pilot; before final gate.
|
||
|
||
**Modify exact component files under `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Shared/Drivers/Forms/`:** `AbCipDriverForm.razor`, `AbLegacyDriverForm.razor`, `FocasDriverForm.razor`, `GalaxyDriverForm.razor`, `HeidenhainDriverForm.razor`, `ModbusDriverForm.razor`, `MqttDriverForm.razor`, `MTConnectDriverForm.razor`, `OpcUaClientDriverForm.razor`, `S7DriverForm.razor`, `SqlDriverForm.razor`, `TwinCATDriverForm.razor` (Calculation completed OT-01).
|
||
|
||
**Also modify exact shared input owners under that UI Components/Shared root:** `Drivers/DeviceModal.razor`, `Drivers/DriverIdentitySection.razor`, `Drivers/DriverResilienceSection.razor`, `Drivers/CollectionEditor.razor`, `Drivers/DriverTagPicker.razor`; `Drivers/DeviceForms/AbCipDeviceForm.razor`, `AbLegacyDeviceForm.razor`, `FocasDeviceForm.razor`, `GalaxyDeviceForm.razor`, `HeidenhainDeviceForm.razor`, `ModbusDeviceForm.razor`, `MqttDeviceForm.razor`, `OpcUaClientDeviceForm.razor`, `S7DeviceForm.razor`, `TwinCATDeviceForm.razor`; and `Uns/TagEditors/AbCipTagConfigEditor.razor`, `AbLegacyTagConfigEditor.razor`, `CalculationTagConfigEditor.razor`, `FocasTagConfigEditor.razor`, `HeidenhainTagConfigEditor.razor`, `ModbusTagConfigEditor.razor`, `MqttTagConfigEditor.razor`, `MTConnectTagConfigEditor.razor`, `NativeAlarmEditor.razor`, `OpcUaClientTagConfigEditor.razor`, `S7TagConfigEditor.razor`, `SqlTagConfigEditor.razor`, `TwinCATTagConfigEditor.razor`; these 13 tag editors and 10 device forms were verified in the current source inventory. Reconcile any later source drift at execution without inventing new protocol forms.
|
||
|
||
**Tests:** extend `tests/Server/ZB.MOM.WW.OtOpcUa.AdminUI.Tests/Pages/FormAccessibilityTests.cs`; keep existing `Drivers/DriverFormMapParityTests.cs` and per-protocol serialization/contract tests.
|
||
|
||
1. Enumerate rendered editable controls and missing names for each protocol in the validation checklist; include picker/modal fields and checkbox labels, not only driver forms. Record unsupported/nonexistent editor files explicitly.
|
||
2. Add representative parameterized render tests (same cascading EditContext harness as OT-01) for actual component types with valid default configs, asserting each editable input/select/textarea has a visible label or intentional accessible name and unique IDs. Run the FormAccessibilityTests filter; expected FAIL on unmigrated fields. Reuse each protocol's existing setup to avoid testing invalid synthetic configurations.
|
||
3. Apply the pilot ID/hint/error recipe in small batches of two or three form families. After each batch run its serialization/contract tests and accessibility cases, then commit only those files with `fix(admin-ui): associate fields in <family names> editors`. Preserve defaults, emitted JSON, connection-versus-device location and runtime parse compatibility.
|
||
4. Extend the same loop to device forms, tag editors, pickers and collection/resilience controls. Modal wrappers from OT-02 must also replace their hand-rendered shells: `Drivers/DriverConfigModal.razor`, `Drivers/DeviceModal.razor`; `Raw/RawNameDialog.razor`, `RawDriverTypeDialog.razor`, `RawBrowseModal.razor`, `RawCsvImportModal.razor`, `RawCsvExportModal.razor`, `RawTagModal.razor`, `RawManualTagEntryModal.razor`, `RawStubModal.razor`; `Uns/AreaModal.razor`, `LineModal.razor`, `ImportEquipmentModal.razor`, `AddReferenceModal.razor`, `VirtualTagModal.razor`, `ScriptedAlarmModal.razor`; inline dialogs in `Pages/Uns/GlobalUns.razor`, `Pages/Scripts.razor`, `Pages/Hosts.razor`. For each two/three-surface batch run modal tests and actual keyboard close/focus cases before committing.
|
||
5. Run baseline Unit command and actual browser field/dialog inventory. Expected all supplied protocols retain accepted serialization and every rendered interactive field/dialog has a verified name/lifecycle. Commit final inventory evidence with OT-14; no “all accessible” assertion from a single pilot.
|
||
|
||
## OT-14 · Family consistency and release gate
|
||
|
||
**Covers:** every OT finding and shared DS-01–06. **Create:** `docs/ui-consistency-validation.md`.
|
||
|
||
1. Run `dotnet build src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/ZB.MOM.WW.OtOpcUa.AdminUI.csproj -c Release`; expected zero new warnings.
|
||
2. Run `dotnet test tests/Server/ZB.MOM.WW.OtOpcUa.AdminUI.Tests/ZB.MOM.WW.OtOpcUa.AdminUI.Tests.csproj -c Release --filter Category=Unit`; expected all Unit tests pass. Then run the full project suite in its configured SQL/integration environment and record actual skipped prerequisites rather than claiming coverage not exercised.
|
||
3. In an isolated synthetic candidate host inspect home, Fleet/Hosts/Diagnostics, Raw/UNS, deployment, log/alerts, security, script editor and shared Secrets. Batch 1440px/390px/200% zoom, keyboard/screen-reader, reduced-motion, loading/empty/filter-empty/error/stale/busy/success and policy cases. Compare same header/toolbar/table/status/dialog patterns with Overview, MxAccessGateway, HistorianGateway, ScadaBridge and ignitionoee. Inspect once; fix observed defects in one batch and confirm at most once.
|
||
4. Record actual Theme/Secrets versions, restored graph, route/field/dialog coverage, screenshots, test counts, performance limits, and outstanding runtime prerequisites. Re-run Impeccable audit and polish last. Mockups are illustrative direction, not a runtime specification for new endpoints/metrics, and source-only review scores are not live conformance scores.
|
||
5. Stage only validation doc and commit `docs(admin-ui): record cross-family UI acceptance evidence`. Produce a reviewable candidate; no feed publish, merge, push or deployment is implied by this chapter.
|
||
|
||
## Complete finding-to-task coverage
|
||
|
||
| Review finding | Plan tasks | Shared references |
|
||
|---|---|---|
|
||
| OT-01 labels/forms/filters | OT-01, OT-13, OT-14 | DS-01/02/04/06 |
|
||
| OT-02 modal lifecycle | OT-02, OT-13, OT-14 | DS-04/05 |
|
||
| OT-03 tree semantics | OT-03, OT-07, OT-14 | DS-04/05 |
|
||
| OT-04 placeholder home | OT-04, OT-14 | DS-05 |
|
||
| OT-05 rail/policy/retired namespace | OT-05, OT-14 | DS-05/06 |
|
||
| OT-06 page/table/title grammar | OT-06, OT-14 | DS-05 |
|
||
| OT-07 narrow/touch | OT-07, OT-14 | DS-04/05 |
|
||
| OT-08 hover-only details | OT-08, OT-14 | DS-04/05 |
|
||
| OT-09 deployment outcomes | OT-09, OT-14 | DS-04/05 |
|
||
| OT-10 tree scope/retry | OT-10, OT-14 | DS-04/05 |
|
||
| OT-11 live/stale/pause | OT-11, OT-14 | DS-04/05 |
|
||
| OT-12 icons/status aliases | OT-12, OT-14 | DS-01/05 |
|
||
|
||
## Rollout / rollback
|
||
|
||
Keep source changes and package-pin adoption reviewable in small commits. Prepare immutable app artifacts and package graph only after G1/shared-Secrets and local gates. Deployment is separately authorized; keep prior app + Theme/Secrets artifacts. Roll back the matched binary/assets/pins if runtime visual acceptance fails; do not roll back configuration data, delete audit evidence, replay deployments or alter wire/security contracts. Preserve independently shipped target-isolation/accessibility fixes when reverting later cosmetic batches. No database migration or driver/protocol change is planned.
|