diff --git a/docs/plans/2026-11-12-scada-ui-consistency.md b/docs/plans/2026-11-12-scada-ui-consistency.md new file mode 100644 index 0000000..4da6e0d --- /dev/null +++ b/docs/plans/2026-11-12-scada-ui-consistency.md @@ -0,0 +1,168 @@ +# SCADA Family UI Consistency Implementation Plan + +> **For Codex:** REQUIRED SUB-SKILL: Use `executeplan` to implement this plan task-by-task. + +**Goal:** Implement the Impeccable recommendations through one improved Technical-Light theme, shared Secrets UI fixes, and coordinated migrations of every sister web UI. + +**Architecture:** First establish one verified bUnit 2.7.2 test baseline across every existing bUnit consumer. The Theme Razor Class Library owns visual foundations and generic interaction contracts; applications retain routes, authorization, data ownership and domain-specific editors. Publish and pilot the shared changes before migrating consumers, using one token/field/focus contract and deliberate product accents. Registry/Perspective receive platform-compatible token/style integration rather than a forced Blazor shell. + +**Tech Stack:** .NET 10/Blazor SSR and InteractiveServer, Bootstrap 5, CSS tokens and IBM Plex, bUnit 2.7.2 with existing xUnit v2/v3 runners, HtmlRenderer/browser harnesses, native Ignition Perspective views/styles. + +--- + +## How to use this plan + +This plan contains **100 tasks across ten chapters**, mapping all **81 review findings**. This is a planning deliverable, not an implementation, package publication or deployment. Start with Phase 0, standardize all existing bUnit users on 2.7.2 and close GB, then execute the shared Theme chapter and project sequence below. Each chapter includes task IDs, exact target files, test-first behavior changes, expected test results, visual checks, commits, finding traceability and rollback. Commands in those chapters are instructions for the future implementation; they were not run during planning. + +- Requirements: [shared design recommendations](../../impeccable/SHARED-DESIGN-SYSTEM.md). +- Evidence and project reports: [review guide](../../impeccable/README.md). +- Visual reference: [13 mockups](../../impeccable/index.html). They illustrate hierarchy with synthetic data; do not port sample counts, names, environment labels or nonfunctional production actions into products. +- Mandatory first phase: [bUnit 2.7.2 standardization](2026-11-12-scada-ui-consistency/BUnit.md) and [seven-project inventory](2026-11-12-scada-ui-consistency/bunit-inventory.json). +- Plan chapters: [folder](2026-11-12-scada-ui-consistency/). +- Revisions: [source baselines](2026-11-12-scada-ui-consistency/source-baselines.json). +- Execution checklist: [task ledger](2026-11-12-scada-ui-consistency/tasks.json). All tasks initially remain planned, not verified. + +The existing scadaproj checkout is suitable for this documentation-only work. At implementation time use a suitable checkout/branch per repository and keep unrelated work intact. Do not create sibling source references across repositories or commit one repository's changes from another working directory. + +## Fixed design decisions + +1. Keep Technical-Light: Plex Sans, Plex Mono for data/code, paper `#f4f4f1`, white working surfaces, fine neutral borders, existing 8px panels, compact rail, consistent controls and status treatment. The plan refines the established identity. +2. Theme is the single authority for shared CSS and components. Do not copy `impeccable/mockups/shared.css` into each application or import mockup-only classes wholesale. +3. Retain source-verified product accents: default blue, Historian green, BTDB teal and Overview purple. Add complete deep/tint/border/focus variants through a shared API; semantic warning/fault/unknown meaning remains uniform. +4. Keep domain distinctions: active ≠ leader; stale ≠ unreachable; accepted deployment ≠ applied configuration; warm pool depth ≠ connections in use; driver eligibility ≠ commissioned/live health; historical write ≠ read query; tombstoned secret ≠ value reveal. +5. Preserve SSR login POST, antiforgery/return-URL validation, current policies, auditing, protocol contracts, lazy loading, precision and cancellation behavior. A visual task must not quietly change these contracts. +6. Make inputs genuinely labeled and errors associated. Name repeated actions with row identity. Keep every task reachable with keyboard and visible focus; dialogs must manage actual focus/inertness, not just ARIA markup. +7. Standardize explicit UTC input semantics where a field says UTC. A `datetime-local` control has no zone; do not call server-local `ToUniversalTime()` and relabel the result. Preserve BTDB's full persisted precision and actual domain parser rules. If local display is kept, label the real zone separately. +8. Keep status text readable, including stale/disabled/help/error states. Fix opacity-based dimming locally after shared inks land. Aim for 44px touch actions while preserving efficient desktop density; assess the separate 24px minimum target/spacing rule accurately. +9. A shared dark-mode expansion is a separate scoped release. Preserve ScadaBridge's existing supported dark mode and provide accessible semantic aliases there; do not remove it or promise all apps support dark mode merely because tokens exist. +10. A native operator layout is appropriate for Perspective. Export the same semantic palette/type/spacing contract into native style resources; do not install a Blazor package in Ignition. +11. Standardize all existing bUnit users on exactly 2.7.2 first, including Theme and ScadaBridge validation plus OtOpcUa preview replacement. Preserve xUnit v2/v3 and non-bUnit harnesses; verify the real parser/Css/Diffing/runtime graph before accepting GB. + +## Phase 0: Baseline, branch ownership and release decisions + +**Owner:** coordinating engineer plus repository maintainers. **Dependency:** none. **Deliverable:** baseline evidence and one chosen shared contract. + +1. Read applicable `AGENTS.md`/repository instructions and the matching report/chapter before editing. Capture `git status --short`, `git rev-parse HEAD`, package pins and existing uncommitted changes per target repo. +2. Compare the actual current source to the [review revision inventory](../../impeccable/evidence/source-inventory.json); do not apply a stale finding to code already fixed. At planning, ScadaBridge moved from `482ac665` to `7e34d7c2` only in Docker image-version stamping; scadaproj moved from `e6a724b` to `d93ca7b` in telemetry/observability. Theme/Secrets/Overview UI source and reviewed ScadaBridge UI source were unchanged by those diffs. +3. Record current unit/component test baselines using the explicit project commands in each chapter. Diagnose infrastructure failures separately; record pre-upgrade test discovery/results before the GB migration. Change bUnit and its necessary test-only compatibility dependencies in that dedicated phase, never disable package audits or perform unrelated dependency upgrades to make UI work pass. +4. Resolve supported browser engines/devices, current color schemes, actual role fixtures and deployment environment overlays. Use synthetic accounts/data for tests; no real secret values in fixtures or screenshots. +5. Assign one owner per repository branch and one owner for Theme. Separate agents may work on separate repositories after shared contracts are agreed. Within scadaproj, Theme/Secrets/Overview package files and shared docs need a single integrator to avoid version conflicts. +6. Resolve the shared release version under the existing token compatibility policy; document the decision. `THEME_VERSION` and `SECRETS_UI_VERSION` in chapters are symbols, not executable package versions. Substitute real versions only after compatibility review/pack validation. + +**G0:** inventory/pre-upgrade baseline recorded, active findings reconciled and contracts assigned. G0 permits the dedicated bUnit migration, not Theme/UI implementation. No live environment change is required to complete planning. + +## Phase 1: Standardize bUnit before shared-theme work + +Execute [BU-01–BU-10](2026-11-12-scada-ui-consistency/BUnit.md). Seven test projects must resolve exact stable **2.7.2** and pass their migrated render/auth/event/async lifecycle suites with an explicitly validated AngleSharp family. Preserve existing runner generations, policy/JSInterop fixtures and test coverage; inspect real restored assets rather than only central version declarations. No bUnit is added to HtmlRenderer/Playwright/native-only projects. + +**GB:** every bUnit project, including existing 2.7.2 consumers, is verified; parser compatibility/advisory disposition, test discovery/results and runtime smoke evidence are recorded. Conflicting repository parser comments are unresolved until actual runtime tests prove the graph. A missing required fixture or unacceptable binary/dependency combination leaves GB incomplete. All Theme/UI tasks and candidate pilots depend on GB; even the independent Secrets target-isolation fix waits for it under this updated ordering. + +## Dependency order and checkpoints + +| Order | Chapter / scope | Depends on | Exit checkpoint | +|---|---|---|---| +| 0 | [bUnit standardization](2026-11-12-scada-ui-consistency/BUnit.md): seven projects, dependency/API migration and runtime verification | G0 | GB: exact 2.7.2 everywhere, accepted graph and passing migrated suites | +| 1 | [Theme](2026-11-12-scada-ui-consistency/Theme.md): semantic inks, field/ARIA API, accent states, busy/focus/motion, interaction recipes | GB | G1: tested, versioned, packaged and piloted Theme plus canonical static export; exact artifacts/version recorded | +| 2 | [Secrets](2026-11-12-scada-ui-consistency/Secrets.md): draft isolation, field associations, modal lifecycle, recovery | GB for target-isolation fix; G1 for visual/field migration | Shared UI package + two-host validation; exact `SECRETS_UI_VERSION` recorded | +| 3 | [Overview](2026-11-12-scada-ui-consistency/Overview.md): first small consumer and read-only visual canary | G1 candidate for local canary; final G1 for released adoption | Readable freshness/check state, truthful rollups, pause/recovery | +| 4 | [ScadaBridge](2026-11-12-scada-ui-consistency/ScadaBridge.md): large interactive pilot | G1 candidate for local canary; final G1/Secrets for released adoption | Modal/drawer access, explicit UTC, truthful count states; light/dark verified | +| 5 | [OtOpcUa](2026-11-12-scada-ui-consistency/OtOpcUa.md) | G1, shared Secrets release where referenced | Labeled forms/trees/dialogs; honest deployment/event states; current route/nav coverage | +| 6 | [MxAccessGateway](2026-11-12-scada-ui-consistency/MxAccessGateway.md) | G1, shared Secrets release where referenced | Keyboard/touch subscription path, managed dialogs, actionable session diagnostics | +| 7 | [HistorianGateway](2026-11-12-scada-ui-consistency/HistorianGateway.md) | G1, shared Secrets release where referenced | Labeled history console; fresh/stale context; reviewed historical write intent | +| 8 | [BTDB](2026-11-12-scada-ui-consistency/BTDB.md) | G1 | Protected drafts, readable teal UI, form/table/tab/JSON-editor recovery | +| 9 | [ignitionoee](2026-11-12-scada-ui-consistency/ignitionoee.md): router, registry, Perspective | G1; platform-compatible export contract | Keyboard job details, unified modal behavior, token parity with native operator views | +| 10 | Cross-family verification and release record | All chapter exits | G3: implemented route/state coverage, no untracked design drift; rollout evidence retained | + +**All rows after order 0 require GB. Avoid a gate cycle:** TH-07 uses local package candidates in temporary Overview/ScadaBridge pilot branches, and TH-08 uses the same canonical static export in a limited registry candidate-import pilot. Those candidate checks do not require the full consumer chapters or a previously released G1. G1 closes after candidate tests and representative pilot surfaces pass; consumer chapters then adopt the released immutable package. A local pilot restore/import does not mean the app is deployed. Reviewed version/source must be committed before the final package build; export provenance records that clean build commit, not a later evidence-only commit. + +**G2: interaction convergence** occurs after two representative dialog/filter/table implementations meet the shared recipes. Compare ScadaBridge's managed dialog and ignitionoee registry's native dialog before extracting generic behavior. Extract only stable common behavior in a later Theme release; domain editors and state logic remain local. G2 does not block independent repairs or G1's recipe publication. + +After G1/required shared UI releases, orders 5–9 can run in parallel with separate repo ownership. The table is a safe serial execution order if only one engineer is available. Do not release each application after a different unresolved token/API contract. + +## Shared APIs and migration rules + +The complete implementations are in the Theme chapter; the following choices are mandatory inputs to every consumer task. + +| Area | Consumer obligation | +|---|---| +| Semantic ink | Use `--ok-ink`, `--warn-ink`, `--bad-ink`, `--idle-ink`; use the new readable `--ink-faint`. Existing `--ok/--warn/--bad/--idle` remain signal colors | +| Field | `TechField For`, `HintId`, `ErrorId` plus explicit control `id`, `aria-describedby`, `aria-invalid`; repeated forms need unique stable IDs | +| Accent | Pass existing `Accent` plus `AccentDeep`, `AccentTint`, `AccentBorder`, `AccentFocus` as a coherent product family. Informational blue uses separate `--info-ink` | +| Busy | Optional `BusyText`, `aria-busy`, existing caller-disabled semantics; caller announces outcome once in a persistent region, never plaintext secrets | +| Table | Labeled filters, caption/header semantics, actual button for sort/disclosure, `aria-sort`/`aria-expanded`, internal horizontal scrolling | +| Overlay | Named dialog, safe initial focus, inert background, actual DOM keydown event, visible enabled focusables only, Escape/cancel policy, return focus | +| Time | Labels match parser/time-zone behavior, exact timestamps available, display age separate from health, no server-zone conversion under UTC labels | +| Error | Failure ≠ empty/zero/success. Preserve safe last-known values and their age, preserve drafts, offer an appropriate retry | + +**Removing duplicate CSS:** inventory both declarations and matching call sites. Compare against the exact adopted package, then delete only identical rules. Keep app-specific geometry, protocol form layout, topology/editor code and supported-scheme overrides until replaced by equivalent shared behavior. + +**Framework compatibility:** GB standardizes all seven current bUnit test projects on 2.7.2 before UI work. Later snippets and fixtures use `BunitContext`, `Render`, `AddAuthorization` and the stable doubles/lifecycle APIs. Retain OtOpcUa xUnit v3 cancellation context and other projects’ xUnit v2; MX/OEE HtmlRenderer and registry Playwright remain unchanged. The exact parser family must pass actual runtime tests. Browser-only focus/layout cannot be established by bUnit/static markup checks. + +## Package adoption ledger + +Source pins below are review/planning baselines, not deployed versions. Confirm actual transitive resolution before each upgrade and record exact selected versions/hashes after execution. + +| Consumer | Baseline | Shared target | Additional checks | +|---|---|---|---| +| Theme source | 0.5.3 | `THEME_VERSION` | Token compatibility policy; retain fonts/static-asset paths | +| Secrets UI source | Theme 0.2.0 dependency; library source currently 0.6.6 | Theme `THEME_VERSION`, library `SECRETS_UI_VERSION` | Restored host graph may already resolve newer Theme; do not downgrade | +| Overview | Theme 0.5.0 | `THEME_VERSION` | Anonymous/read-only; purple accent | +| ScadaBridge | Theme 0.5.3 | `THEME_VERSION`, required Secrets package | Existing local dark palette, sandbox/editor boundaries and audit lifecycle | +| OtOpcUa | Theme 0.5.0 | `THEME_VERSION`, required Secrets package | SSR/interactive routes; raw/UNS trees; driver authoring invariants | +| MxAccessGateway | Theme 0.5.0 | `THEME_VERSION`, required Secrets package | Worker/COM workflow acceptance requires its actual platform | +| HistorianGateway | Theme 0.5.0 | `THEME_VERSION`, required Secrets package | Green accent; `.rail-btn` usage; live historian writes only in approved test target | +| BTDB Manager | Theme 0.4.1 | `THEME_VERSION` | Teal accent; audit/transfer semantics and 7-digit time precision | +| ignitionoee router | Theme 0.5.0 | `THEME_VERSION` | Policy gates, offline/site sync and schedule/data semantics | +| ignitionoee registry | Local token/shell CSS | Versioned canonical static CSS/token export | No blind domain stylesheet deletion; preserve native dialog and editor geometry | +| Perspective operator views | Native view/style JSON | Platform-compatible versioned token/style mapping | Native Ignition resources, no Blazor dependency, existing role/site/offline rules | + +Registry deliberately remains on its documented public-NuGet-only dependency policy. G1 therefore includes a versioned static CSS/font/token export generated from the exact reviewed Theme package. Registry vendors verified assets under `registry/src/Registry.Host/wwwroot/shared-theme/` and retains native markup/domain CSS. Perspective initially maps canonical tokens into existing native `props.style` resources; use named style classes only after a Designer-exported fixture proves their resource format. Neither integration becomes a hand-maintained palette fork. + +## Test and visual acceptance matrix + +Execute the smallest meaningful regression first, make it fail for the specific observed defect, implement the minimal fix, then run the affected project suite. Keep existing tests that protect protocol, audit, authorization, precision and disabled behavior. Do not write unit tests merely restating a margin/color declaration; inspect real rendered styles instead. + +| Dimension | Required cases and evidence | +|---|---| +| Viewports | 1440×900 desktop, 1024×768 short desktop, 390×844 phone, actual browser 200% zoom; supported Chromium/Firefox/WebKit engines as agreed at G0 | +| Navigation | Mobile closed/open keeps content visible; long rail scrolls; session/footer reachable; current location truthful; policy-allowed destinations only | +| Keyboard | Tab/Shift+Tab, Enter/Space, Escape where appropriate; sortable headers, row disclosures and tree expanders; focus visible and not clipped | +| Screen reader | Programmatic names/descriptions, exact modal title, validation/recovery, no repeated announcement flood or secret disclosure | +| Color | Computed text contrast ≥4.5:1 for ordinary small text; large text/nontext UI/focus as applicable ≥3:1; stale opacity, theme overrides and every supported scheme | +| Motion | Reduced motion presents final content; state is still textual and immediate | +| State | Initial load, pending, empty, no-match, denied, unavailable, stale/paused, busy, success, validation failure, backend failure, cancellation/conflict | +| Data scale | Long identifiers/error text, deep tree, lazy/unloaded branches, large inventory; scoped horizontal scroll and preserved selection | +| Time | UTC boundaries, server/browser in different zones, daylight-saving edge where local display exists, exact persisted precision, sample age vs latest attempt | +| Safety semantics | Duplicate submission prevented; commit and subsequent reload/audit outcomes kept distinct; no retry of an already committed action; correct row/target identity | +| Operational truth | Protocol/controller/worker failures never painted healthy; unavailable counts are unknown; evidence/eligibility and application/runtime state stay distinct | + +For every representative screen save route, commit, viewport, role, scheme, fixture description, screenshot and keyboard/state result. Use synthetic fixture data; redact operational identifiers where the local process requires it. A screenshot proves composition only; it does not prove server authorization or database correctness. + +**Representative route coverage:** each chapter's finding-to-task table covers its recommendations, and its route-family inventory drives regression sampling. Extend automated coverage to the real failure paths; the 13 concepts are not the entire route set. The initial active-source inventory discovered 168 route declarations across the indexed checkouts, including aliases and hosted shared pages; route declarations are not equivalent to distinct runtime screens. + +## Rollout, rollback and completion + +1. Close GB and record exact bUnit/parser versions and migrated suite evidence first. Then finish the shared library/unit/component checks and two local candidate pilots; record G1 and actual immutable package/hash. +2. Ship shared Secrets UI once its target-isolation and interaction tests pass; resolve the consumer graph explicitly rather than assuming source and host pins are equal. +3. For each consumer, commit package adoption separately from domain UX changes where practical. Keep commits small enough to identify a specific regression; preserve pre-upgrade package lock and application artifact. +4. Run the chapter's focused and full checks, compare real screens to the same shared contract, then run @impeccable audit and one bounded @impeccable polish. Re-audit findings rather than treating a detector-empty result as accessibility conformance. +5. Publish/deploy only through the relevant repository's documented release process with the execution session's authorization. This plan does not itself authorize production mutations or live historian/secret operations. +6. Use the existing development environment first, then QA, then each approved target. Clustered deployments follow the application's paired-node/migration procedures; a UI-only plan must not rewrite those procedures. Native Ignition resources require schema validation and Designer/session acceptance. +7. Rollback the whole validated application artifact and its pinned package set. Do not restore only CSS while leaving components expecting a new API. For native styles, keep the prior resource export. A rollback cannot reverse audited data mutations; these changes are designed to require no schema migration. +8. For each gate, record actual test results, screenshots, restored package versions, environment and remaining blockers. Record infrastructure-blocked checks explicitly and leave their tasks incomplete. Do not claim a live pass from offline or mockup tests. +9. Mark G3 complete only after every P1 and agreed P2 task has passed its chapter acceptance, shared DS findings are adopted consistently, optional work has an explicit disposition, and no regression is hidden by local palette/component copies. + +## Deferred product choices + +These are recommendations requiring evidence or a product decision, not reasons to stop the implementation plan: + +- Timed secret auto-hide: implement predictable reveal/hide focus and announcements first; choose exposure timing separately, with warning/extension behavior if required. Do not introduce silent timeouts. +- Overview list/attention mode: keep full-fleet topology as default; add an optional filter/list only with confirmed state/scale semantics. +- Generic modal component: extract after two pilots; use validated local adapters first. +- Full shared dark scheme: preserve current supported dark UI and accessible aliases; separate expansion into a fully tested Theme release. +- Perspective named style-class extraction: first use generated mappings in existing native views; introduce named resources only after a valid Designer-exported fixture establishes their format. +- Virtualization or memoization: measure realistic render/data cost before adding complexity; preserve lazy-loading scope and real state behavior. + +## Final execution record + +Each chapter's task IDs and coverage table are the source for [tasks.json](2026-11-12-scada-ui-consistency/tasks.json). Update that ledger only after the corresponding evidence exists. Implementation should use @executeplan with a batch review checkpoint after bUnit standardization, shared Theme, shared Secrets, each sister application, and the cross-family release pass. @writeplan produced these documents; no product code was changed by the planning task. diff --git a/docs/plans/2026-11-12-scada-ui-consistency/BTDB.md b/docs/plans/2026-11-12-scada-ui-consistency/BTDB.md new file mode 100644 index 0000000..94437a8 --- /dev/null +++ b/docs/plans/2026-11-12-scada-ui-consistency/BTDB.md @@ -0,0 +1,228 @@ +# BTDB Manager UI Consistency Implementation Plan + +> **For Codex:** REQUIRED SUB-SKILL: Use `executeplan` to implement this plan task-by-task. + +**Goal:** Align BTDB Manager with the Theme-first suite refinements while preserving precise audited edits and making forms, overlays and recovery accessible. + +**Architecture:** Keep the InteractiveServer host and existing Manager.Core repositories/transactions, role gates, read-only lot context, preview/import planner and PDF reports. Adopt the validated shared package and recipes; keep BTDB-specific edit/row/diff state local. Reuse the documented ScadaBridge dialog pilot contract for a second consumer before considering generic RCL extraction. + +**Tech Stack:** .NET 10 Blazor InteractiveServer without prerendering, Bootstrap 5, Theme RCL, xUnit 2.9.3, bUnit 2.7.2 after GB (`BunitContext` / `Render`), existing repository fakes and WebApplicationFactory boot tests. Keep the GB-validated test stack unchanged during UI implementation. + +--- + +## 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 shared dependencies + +- Active repo `/Users/dohertj2/Desktop/BTDB`, plan baseline `5b89798`. Theme is **0.4.1** in `src/ZB.MOM.WW.BTDB.Manager/ZB.MOM.WW.BTDB.Manager.csproj:27`; this repo intentionally does not use central package management. Do not add Directory.Packages.props. +- Inputs: `/Users/dohertj2/Desktop/scadaproj/impeccable/BTDB.md` BT-01–11 and shared design contract. Existing teal **#1b7f8e** remains product identity inside the common Plex/neutral-paper/rail system. The mockup is a layout/behavior illustration; example records are not new backend requirements. +- **G1 prerequisite for visual adoption:** validated immutable Theme artifact with symbolic `THEME_VERSION` replaced only by its assigned real version. Semantic text tokens: `--ok-ink:#236f34`, `--warn-ink:#855000`, `--bad-ink:#b42121`, `--idle-ink:#535d66`, `--ink-faint:#626970`; `--info-ink` is semantic blue independent of product teal. Additive TechField `For/HintId/ErrorId` and shell `AccentDeep/AccentTint/AccentBorder/AccentFocus` retain compatibility. TechButton BusyText is optional, aria-busy identifies pending work, and caller owns outcome announcements. G1 also documents focus/reduced-motion/table/filter/dialog recipes. +- Local correctness repairs may start after GB closes and the contract is agreed; package-dependent visual merge waits for G1. BT-01 native-event modal wiring follows the ScadaBridge pilot, preserving capture/restore behavior but avoiding delayed `window.event`; after both consumers pass, parent G2 can assess generic extraction. Do not introduce a new global modal framework now. +- Preserve existing machine/group/BatchEdit policies, existing batch editing only, datetime2(7) precision, UTC edit/query semantics, report-time Machine.TimeZone conversion, reason/audit attribution, concurrency handling and transaction rollback. No database migration, secret, production fixture, service restart or deploy is required by this planning request. + +## Exact path notation, baseline and execution rules + +All commands use cwd `/Users/dohertj2/Desktop/BTDB`. File-inventory prefixes expand exactly: + +```text +U = src/ZB.MOM.WW.BTDB.Manager +C = src/ZB.MOM.WW.BTDB.Manager.Core +T = tests/ZB.MOM.WW.BTDB.Manager.Tests +``` + +Set task-specific shell variables when executing: + +```sh +BT_UI=src/ZB.MOM.WW.BTDB.Manager +BT_TEST=tests/ZB.MOM.WW.BTDB.Manager.Tests/ZB.MOM.WW.BTDB.Manager.Tests.csproj +git status --short +dotnet test "$BT_TEST" -c Release +``` + +Expected baseline pass, or record an independent existing failure before starting. `build.sh` already runs restore/build/test on BTDB.slnx; preserve it. Perform the prescribed test-pin/API/parser changes in GB first. After GB, parser/package failure is a regression to investigate, not an expected UI red state or a reason for another incidental upgrade. + +For each behavioral change: write the specified regression in existing fixtures, run its exact filter and confirm the expected assertion fails, implement the minimum fix, rerun filter, run related tests, commit only named changes. bUnit cannot prove focus movement/contrast/overflow; browser checks supply that evidence. CSS-only work uses screenshot/computed-style verification, without tests duplicating CSS declarations. New files below are marked create. Plan writing itself performs none of these implementation steps. + +## Task BT-00: Capture and adopt the validated shared package + +**Files:** Modify `U/ZB.MOM.WW.BTDB.Manager.csproj`, inspect `U/Components/App.razor`, `U/Components/Layout/MainLayout.razor`, `U/wwwroot/css/site.css`; create `docs/ui-consistency/BTDB-verification.md` and implementation screenshot directory `docs/ui-consistency/screenshots/`. + +1. Record previous pin, actual G1 package version/digest, current repo changes and baseline test result. Capture login, overview, machines, machine form, find batch, batch edit, config import and audit/PDF-view context at desktop/tablet/phone before the bump. +2. Replace the direct Theme version with the real `THEME_VERSION` supplied by G1. Keep existing Bootstrap/Theme/site/scoped CSS load order and no-prerender setting; preserve lazy Monaco and asset cache busting. +3. Run `dotnet restore "$BT_TEST"` and `dotnet test "$BT_TEST" -c Release`; expected existing behavior passes. Browser capture 1440×900, 768×1024, 390×844, 200% zoom, mobile nav closed/open; content and footer remain visible. A package bump alone must not silently rewrite all component styles. +4. Do not start a host automatically while writing the plan. During implementation choose an existing disposable dev fixture; local documented port is 9877 and requires a test ConnectionStrings__BT environment value. Record actual URL/auth state without committing credentials. A server cannot be assumed healthy merely because `dotnet build` passes. +5. Commit explicit package/verification files, `git commit -m "chore(ui): adopt validated BTDB theme package"`. Preserve the prior artifact/pin for rollback. + +## Task BT-01: Restore full modal keyboard behavior in two local adapters + +**Maps:** BT-01. **Depends:** documented G1 overlay recipe and ScadaBridge pilot behavior, not a hypothetical generic modal API. +**Files:** Modify `U/Components/Shared/DialogHost.razor`, `EditableRows.razor`, `U/Components/App.razor`, `U/wwwroot/css/site.css`; create `U/wwwroot/js/dialog.js`, `tools/ui_consistency_browser.py`; extend `T/Shared/DialogServiceTests.cs`, `EditableRowsTests.cs`. + +1. Extend existing dialog/row fixtures with close/focus-lifecycle assertions and preserve typed result/Cancel rollback tests. Add `Editor_CancelRestoresSnapshotAndRemovedFocusTargetIsSafe`: edit an existing cloned row, Cancel, assert original data/state restored; remove trigger before close and assert component cleanup does not throw. Run `dotnet test "$BT_TEST" --filter 'FullyQualifiedName~DialogServiceTests|FullyQualifiedName~EditableRowsTests'`. +2. Unit markup tests should assert named modal, proper disabled state and clean close behavior; do not mistake loose JSInterop no-ops for a real focus-trap test. Existing rollback tests may already pass; retain them as regression protection rather than forcing a fake red result. +3. Write real-browser red case using `playwright.sync_api` in the new script, with explicit `--base-url`, `--storage-state`, `--output-dir`, `--case overlays`. Record that Tab from final button currently reaches blocked background. Script must only open/cancel fixture dialogs and may not submit a production save/import. +4. Reuse the proven DOM behavior contract in BTDB namespace: capture opener before initial focus; add an actual element-bound keydown listener; synchronous event.preventDefault at Tab boundaries; exclude hidden/inert/disabled controls; handle zero-focusable dialog; body lock/background inert; Escape cancel; remove listeners on close/dispose; restore connected trigger or stable page context. Track state per overlay; do not copy ScadaBridge's old window.event dependency. Preserve Enter/default form behavior and stop Escape closing two nested overlays. +5. Reference `/js/dialog.js?v=@AssetVersion` from App before Blazor, retaining existing versioning. Wire both local adapters to the same lifecycle. Preserve Clone rollback and cancellation of a newly added row; never implement Done as immediate database save. +6. Run focused unit tests then `python3 tools/ui_consistency_browser.py --base-url "$BT_REVIEW_URL" --storage-state "$BT_REVIEW_STATE" --output-dir docs/ui-consistency/screenshots --case overlays`. Expected red pre-change / green after: first/last Tab and Shift+Tab contained, Escape returns to initiating row, hidden tabs skipped, short-dialog footer reachable. +7. Commit explicit named files, `git commit -m "fix(ui): preserve keyboard context in BTDB dialogs"`. Record successful second pilot for the parent G2 extraction decision; do not extract a shared generic component in this task. + +## Task BT-02: Connect field labels, validation and editor names + +**Maps:** BT-02. **Depends:** BT-00 for TechField adoption; direct id/for repairs may precede it. +**Files:** Modify `U/Components/Pages/Machines/MachineForm.razor`, `MachinesList.razor`, `U/Components/Pages/MachineGroups/MachineGroupForm.razor`, `U/Components/Pages/Batches/BatchEdit.razor`, `U/Components/Shared/DialogHost.razor`, `JsonEditor.razor`, `U/wwwroot/js/json-editor.js`; extend `T/Pages/Machines/MachineFormTests.cs`, `MachinesListTests.cs`, `T/Pages/MachineGroups/MachineGroupFormTests.cs`, `T/Pages/Batches/BatchEditPageTests.cs`, `T/Shared/JsonEditorTests.cs`. + +1. In existing MachineFormTests reuse RegisterFakeRepository/BuildSampleMachine/AuthorizeAsAdministrator. Add `CodeInput_IsNamedByVisibleLabel` with render setup already used by the class: + +```csharp +var cut = Render(p => p.Add(c => c.Id, SampleMachineId)); +var label = cut.FindAll("label").Single(e => e.TextContent.Trim() == "Code"); +var id = label.GetAttribute("for"); +Assert.False(string.IsNullOrWhiteSpace(id)); +Assert.Equal("Z001", cut.Find("#" + id).GetAttribute("value")); +``` + +Add corresponding field-error association after invalid submission, populated search/group filter naming and repeated work-order row-editor uniqueness. For JsonEditor test forwarded ariaLabel options, not Monaco internals. +2. Run `dotnet test "$BT_TEST" --filter 'FullyQualifiedName~MachineFormTests|FullyQualifiedName~MachinesListTests|FullyQualifiedName~MachineGroupFormTests|FullyQualifiedName~BatchEditPageTests|FullyQualifiedName~JsonEditorTests'`; expected red: missing id/for or editor field-name relationship. +3. Give visible labels stable ids/for. Use G1 TechField additively where appropriate; caller still connects input id/error/hint/invalid attributes. Add optional local JsonEditor Label/HintId/ErrorId contract; pass meaningful ariaLabel to Monaco and fallback textarea; keep document-specific names for every editor. +4. Keep required/validation business rules; align hints and errors without replacing timestamp parsing or row models. Cover group form, import filters, prompt, batch/work-order/cycle/transfer editors; do not attach duplicate ids in hidden panes. +5. Rerun focused tests and screen-reader forms-mode checks; check invalid controls announce both field and corrective hint. Commit explicit files, `git commit -m "fix(ui): name BTDB fields and validation context"`. + +## Task BT-03: Guard dirty navigation without changing save transactions + +**Maps:** BT-03. **Files:** Create `U/Components/Shared/UnsavedChangesGuard.razor`, `T/Shared/UnsavedChangesGuardTests.cs`; modify `U/Components/Pages/Machines/MachineForm.razor`, `U/Components/Pages/MachineGroups/MachineGroupForm.razor`, `.razor.cs`, `U/Components/Pages/Batches/BatchEdit.razor`; extend existing MachineFormTests, MachineGroupFormTests, BatchEditPageTests; extend browser script. + +1. Test the guard through NavigationManager and real/stub existing IDialogService: clean navigation proceeds without prompt; dirty + Stay prevents location change; dirty + Discard proceeds once; a second navigation prompts again. Add page integration tests for row-only dirty changes, failed save retaining guard and successful save bypassing guard exactly once. +2. Run `dotnet test "$BT_TEST" --filter 'FullyQualifiedName~UnsavedChangesGuardTests|FullyQualifiedName~MachineFormTests|FullyQualifiedName~MachineGroupFormTests|FullyQualifiedName~BatchEditPageTests'`; initial red: guard missing or dirty navigation proceeds. Use bUnit test navigation history/registered handlers, not a test that simply counts component tags. +3. Minimal local component uses the existing dialog service and built-in NavigationLock (add the routing namespace import): + +```razor +@using Microsoft.AspNetCore.Components.Routing +@inject IDialogService Dialog + +@code { + [Parameter] public bool IsDirty { get; set; } + private async Task BeforeNavigate(LocationChangingContext context) + { + if (!IsDirty) return; + var discard = await Dialog.ConfirmAsync("Discard unsaved changes?", + "Leave this page and discard the pending edits?"); + if (!discard) context.PreventNavigation(); + } +} +``` + +On Stay prevent navigation; on accepted discard allow that navigation. Serialize overlapping navigation attempts so rapid clicks cannot open two confirmations; if disposal occurs while awaiting, do not act on a stale navigation context. Never auto-save on leave. Native browser unload confirmation has browser-owned text and cannot await an async server dialog. +4. Wire current dirty calculations including child rows and edit reason. Set successful-save/explicit-discard state before final navigation; do not disable the guard merely while a failing save is pending. Reload-conflict button must explicitly warn that it discards pending values. Reuse one confirmation path to avoid double prompts on Cancel. +5. Browser check rail, Back, refresh, close tab, external navigation, form Cancel, conflict Reload, row-editor Cancel, failed save and successful save using disposable data. No draft-persistence claim is added. Check disconnected circuit message still says unsaved changes are not kept. +6. Rerun tests then browser `--case dirty-navigation` added to the script. Commit explicit files, `git commit -m "fix(ui): guard unsaved BTDB edits on navigation"`. + +## Task BT-04: Migrate semantic ink and preserve teal identity + +**Maps:** BT-04. **Depends:** BT-00/G1. +**Files:** Modify `U/wwwroot/css/site.css`, `U/Components/Layout/MainLayout.razor`, `U/Components/Pages/ConfigImport/ConfigImport.razor.css`, `U/Components/Pages/Machines/MachineForm.razor.css`; update verification notes. + +1. Record before computed color pairs for JSON caption, inactive tab, import hint, row-added/edited/removed chip and toast dismissal. No unit tests duplicating CSS values. +2. Change textual row/change/status usages to semantic ink tokens; reserve saturated status colors for dots/decoration. Keep informational status blue via --info-ink even when product Accent is teal. Keep inactive/removed text readable and labelled; strike-through/color alone is insufficient to explain row removal. +3. Pass audited teal deep/tint/border/focus values through the G1 additive shell parameters after visual comparison; retain existing Accent. In particular existing --accent-deep must not silently stay blue while primary buttons/nav are teal. Put shared values in Theme-approved product configuration, not a new uncoordinated palette per page. +4. Measure normal text ≥4.5:1 and relevant nontext/focus ≥3:1 on actual surfaces. Verify no color-only meaning, copied values/selected text readable, and reduced-motion keeps focus/feedback visible. BTDB currently has no dark-mode feature; do not invent one in this chapter. +5. Run `dotnet test "$BT_TEST" -c Release` to protect semantic behavior; screenshot desktop/tablet/phone once, fix once and confirm. Commit named files/notes, `git commit -m "style(ui): adopt semantic inks and coherent BTDB accent"`. + +## Task BT-05: Finish machine-form tab behavior + +**Maps:** BT-05. **Files:** Modify `U/Components/Pages/Machines/MachineForm.razor`, `.razor.css`; extend `T/Pages/Machines/MachineFormTests.cs` and browser script tabs case. + +1. Add `Tabs_ReferenceLabelledPanels_AndPreserveDraft`: each tab references an existing panel id, active tab tabindex 0, others -1; panel aria-labelledby points back. Edit OtherData, switch to Memberships and back, assert draft persists. Add Right/Left/Home/End keyboard selection tests with existing machine fixture. +2. Run `dotnet test "$BT_TEST" --filter FullyQualifiedName~MachineFormTests`; expected red: absent relationships and key behavior. Existing all-panes-rendered test stays valid; do not change hidden panel persistence. +3. Assign ids/controls/labelledby and implement roving focus following shared tab recipe. Keep inactive panels hidden and their values rendered. Focus must reach active tab only once in normal tab order; handle arrow key defaults synchronously if native event prevention is needed. +4. Browser Tab → active tab; arrows change/focus; Home/End move boundaries; Tab enters visible panel. No hidden editor focus target may be included in modal trap. At phone width wrap/scroll tab labels without clipping active indicator. +5. Rerun filter then browser `--case tabs`. Commit three explicit files, `git commit -m "fix(ui): complete BTDB machine form tab navigation"`. + +## Task BT-06: Adapt forms and row dialogs for phone/touch + +**Maps:** BT-06. **Files:** Modify `U/wwwroot/css/site.css`, `U/Components/Pages/Machines/MachineForm.razor.css`, `U/Components/Pages/ConfigImport/ConfigImport.razor.css`; update verification notes. + +1. Capture existing three/two-column identity form and 80vw row dialog at 390px and 200% zoom with long timezone, machine code, validation and multiple checkboxes. Use screenshot evidence; no mirrored CSS unit tests. +2. At narrow widths reduce .form-grid/.cols-3 to one column, reset span-2 semantics, allow .check-row wrap. Give row dialog near-full phone width, bounded dvh-compatible height/body scrolling and visible actions. Preserve compact desktop density and the permanent no-entrance-animation fix for panels hosting EditableRows. +3. Increase coarse-pointer hit regions to practical ≥44px without making every desktop data row oversized. Keep table overflow local; avoid blocking a nested scroll at short landscape heights. +4. Run `dotnet test "$BT_TEST" --filter 'FullyQualifiedName~EditableRowsTests|FullyQualifiedName~MachineFormTests|FullyQualifiedName~ConfigImportPageTests'`; expected behavioral pass. Browser verify phone/tablet/landscape/zoom and keyboard focus visibility with form errors. +5. Commit named CSS/notes, `git commit -m "style(ui): adapt BTDB forms and row editors for touch"`. + +## Task BT-07: Recover from failed Monaco initialization + +**Maps:** BT-07. **Files:** Modify `U/Components/Shared/JsonEditor.razor`, `U/wwwroot/js/json-editor.js`; extend `T/Shared/JsonEditorTests.cs`. + +1. Add `InitializeFailure_ShowsNamedFallbackWithoutLosingValue`: configure strict JSInterop createEditor to throw JSException, render with a valid original string, assert visible initialization error and labelled textarea/fallback preserves value. Edit fallback, assert ValueChanged and existing parse validation. Retry success must preserve edited text and remove stale fallback/error; disposal must not leave an orphan editor. +2. Run `dotnet test "$BT_TEST" --filter FullyQualifiedName~JsonEditorTests`; expected red: failure only logged and empty host remains. Test async result/wait path with existing strict interop style; do not globally loosen calls to hide errors. +3. Add explicit loading/ready/failed initialization state and retry path; failed state renders a labelled bound plain-text editor using the same validation/value pipeline and ReadOnly setting. Keep original/updated bound text on every state transition. Record JS failures for diagnosis without exposing stack detail in UI. +4. Monaco create options receive field ariaLabel from BT-02; optional format action becomes available only when ready. Keep lazy assets and worker paths; retry must not initialize duplicate editor instances. Existing echo-suppression/value restore tests remain. +5. Rerun filter; browser block script/worker request, retry, invalid/valid JSON and disconnected circuit with no value loss. Commit three files, `git commit -m "fix(ui): recover BTDB JSON editor initialization"`. + +## Task BT-08: Reconcile shared page anatomy and version compatibility + +**Maps:** BT-08. **Depends:** BT-00, BT-04. +**Files:** Modify `U/wwwroot/css/site.css`, `U/Components/Layout/MainLayout.razor`, `U/Components/Pages/Overview/Overview.razor`, `U/Components/Pages/Machines/MachinesList.razor`, `MachineForm.razor`, `U/Components/Pages/MachineGroups/MachineGroupsList.razor`, `MachineGroupForm.razor`, `U/Components/Pages/Batches/FindBatch.razor`, `BatchEdits.razor`, `BatchEdit.razor`, `U/Components/Pages/ConfigImport/ConfigImport.razor`, `U/Components/Pages/Audit/AuditIndex.razor`, `MachineAudit.razor`, `MachineGroupAudit.razor`, `BatchEditAudit.razor`; update verification notes and existing relevant semantic tests only if headings change. + +1. Build ownership table for shared .page-head/.panel/.data-table/.btn vs legitimate BTDB .diff/.editable-rows/.form-grid. Verify actual package rules; keep local overrides where no shared replacement exists. +2. Move compact h1/action/meta anatomy to G1 pattern across every family, including AuditIndex which currently lacks a page h1. Add one semantic test `AuditIndex_HasSinglePageHeading` to `T/Pages/Audit/AuditIndexTests.cs`; red before heading, green after. Do not snapshot every margin or class. +3. Remove/reconcile duplicate .page-head and spread page action CSS only after computed layout matches shared family. Keep custom row/editor/diff components local; keep import steps numbered because sequence is meaningful. Avoid nested panel containers for errors while preserving role=alert. +4. Run `dotnet test "$BT_TEST" --filter 'FullyQualifiedName~AuditIndexTests|FullyQualifiedName~MachineFormTests|FullyQualifiedName~BatchEditPageTests|FullyQualifiedName~ConfigImportPageTests'`; compare header/table/action sizing and mobile closed-nav behavior to same-suite fixtures. +5. Commit explicit modified paths, `git commit -m "refactor(ui): align BTDB page anatomy with shared theme"`. Do not introduce a numeric release or change other dependencies. + +## Task BT-09: State UTC before date entry and retain precision + +**Maps:** BT-09. **Files:** Modify `U/Components/Pages/Batches/FindBatch.razor`, `BatchEdits.razor`, optionally `U/Components/Shared/DateTimeRangeFilter.razor` for additive zone hint only; extend `T/Pages/Batches/FindBatchTests.cs`, `BatchEditsTests.cs`, `T/Shared/DateTimeRangeFilterTests.cs`. + +1. Add `BeforeSearch_CustomWindowIsExplicitlyUtc`: render FindBatch using existing repository fixture before _searched, assert field/zone guidance already says UTC. Submit exact UTC boundaries and assert repository receives those unchanged; inverted range emits no search and preserves values. Add cross-host-zone data cases through existing fake callback rather than modifying system clock. +2. Run `TZ=America/Indianapolis dotnet test "$BT_TEST" --filter 'FullyQualifiedName~FindBatchTests|FullyQualifiedName~DateTimeRangeFilterTests|FullyQualifiedName~BatchEditsTests'`; expected red on missing initial guidance; timestamp-preservation tests may already pass and protect current behavior. Repeat after fix under `TZ=UTC` and `TZ=Asia/Tokyo`. +3. Label range “Start time window (UTC)” and/or suffix field labels before input; repeat UTC on applied filter/export results. Keep DateTimeRangeFilter input-only, stored edit timestamps UTC and full datetime2(7) batch-editor precision. Do not apply Machine.TimeZone at edit/query time; it belongs to reporting. +4. Browser choose the same UTC boundaries from UTC/Indianapolis/Tokyo contexts and around DST dates; same known batch result. UTC edits have no ambiguous local-time conversion. No generic browser-local policy is introduced. +5. Commit exact component/test files, `git commit -m "fix(ui): state UTC before BTDB time-window entry"`. + +## Task BT-10: Remove misleading sort cues and verify table scale + +**Maps:** BT-10. **Files:** Modify `U/Components/Pages/Machines/MachinesList.razor`, `U/Components/Shared/DataTable.razor`; extend `T/Shared/DataTableTests.cs`; inspect `U/Components/Pages/Batches/BatchEdits.razor`, `U/Components/Pages/Audit/AuditIndex.razor`, `C/Services/DbRepository.cs` without changing SQL in this UI task. + +1. Add `NamedOverflowRegionRetainsTableHeaders`: render a table with a meaningful label, assert labelled region/table relationship and accessible headers/count. Initial red: component has no label API. Use optional TableLabel parameter with meaningful safe default and named callsites; do not assert scroll behavior in AngleSharp. +2. Run `dotnet test "$BT_TEST" --filter FullyQualifiedName~DataTableTests`; expected missing parameter/assertion red, then pass after wrapper API/markup change. +3. Remove Code .sortable appearance because no sorting behavior exists; do not add new sorting merely to justify a class. Preserve current query order. Add labelled/focusable overflow region only where needed, avoid duplicate nested scroll areas; keep blank action header accessible as Actions. +4. Measure batch-edit and audit-index load/query/browser render on a representative large disposable history, record item count, payload size, query time and input responsiveness in verification notes. Current whole-history client filtering is known; do not claim a measured bottleneck before capture. If unacceptable, create a separately scoped repository/server-pagination follow-up with measured budget and parity tests; leave this UI consistency change bounded. +5. Browser long values at 390px/200% zoom, local horizontal scroll and accessible action names. Rerun DataTableTests/BatchEditsTests; commit exact files, `git commit -m "fix(ui): clarify BTDB table controls and overflow"`. + +## Task BT-11: Promote the review workflow and complete suite acceptance + +**Maps:** BT-11. **Depends:** preceding tasks. +**Files:** Modify `U/Components/Pages/Overview/Overview.razor`, `.razor.css`, `U/Components/Pages/Batches/BatchEdit.razor`, `U/wwwroot/css/site.css`; extend `T/Pages/Overview/OverviewTests.cs`, `T/Pages/Batches/BatchEditPageTests.cs` as needed for changed visible behavior; update verification notes/browser cases. + +1. Add role regression `Overview_FindBatchShortcutOnlyForBatchEdit`: reuse existing authorization fixtures, render Viewer then BatchEdit policy, verify shortcut visibility and retained read-only audit destinations. Run `dotnet test "$BT_TEST" --filter FullyQualifiedName~OverviewTests`; red before new shortcut, green with policy gate. +2. Compress six equal counts into shared facts strip, promote recent edits and a policy-gated Find a batch action; keep all count meanings and existing access info available in a disclosure. Do not invent a real-time monitor or new batch-creation CTA. +3. Keep batch machine/id/UTC context visible beside reason/change summary and pending state. Use “Review changes” before existing audited Save confirmation; avoid extra confirmation for harmless field edits. Retain original values, row change counts and lot context; no fabricated production diff from mockup. +4. Run `dotnet test "$BT_TEST" -c Release` and existing Manager.Core tests with `dotnet test tests/ZB.MOM.WW.BTDB.Manager.Core.Tests/ZB.MOM.WW.BTDB.Manager.Core.Tests.csproj -c Release`. Expected pass. Integration tests requiring BTDB_TEST_CONNECTION remain separately identified, not silently counted as run; use a disposable test DB if later execution requires DB checks. +5. Run new browser cases on the supplied fixture, capture all route families once in desktop/tablet/phone/zoom, inspect focus/contrast/overflow/states in the same batch, fix once then confirm. Verify PDF-related existing tests still pass; do not rewrite PDF layout solely to match web chrome. +6. Commit explicit page/test/verification files, `git commit -m "refactor(ui): prioritize BTDB change review and recent edits"`. + +## Coverage, rollout and rollback + +| Report finding | Task | Acceptance evidence | +|---|---|---| +| BT-01 modal behavior | BT-01 | native browser Tab/Shift+Tab/Escape/focus return + row rollback | +| BT-02 field names | BT-02 | visible label/error relationships, named editor and populated filters | +| BT-03 dirty navigation | BT-03 | Stay/Discard, Back/refresh/Cancel/save/conflict paths | +| BT-04 readable tokens | BT-04 | computed contrast pairs, semantic blue separate from teal | +| BT-05 tab semantics | BT-05 | linked panels, roving focus and drafts survive switching | +| BT-06 phone forms | BT-06 | single-column/coarse-pointer/short-viewport browser captures | +| BT-07 JSON recovery | BT-07 | JS init failure/fallback/retry/value preservation | +| BT-08 shared anatomy/version | BT-00/08 | recorded real package, one title system, mobile closed-nav | +| BT-09 UTC entry | BT-09 | guidance before first query, exact UTC boundaries and precision | +| BT-10 sort/overflow/scale | BT-10 | honest controls, keyboard local scrolling, measured history size | +| BT-11 task hierarchy | BT-11 | role-appropriate shortcut and unchanged audited review flow | + +**State/role matrix:** Viewer / MachineConfig / BatchEdit / Administrator; no configured vs filtered-zero; loading vs unavailable; open/closed batch; added/edited/removed/restored child; invalid precision/JSON/range; optimistic-concurrency conflict; save rollback; missing username; empty/stale import preview; import failure; no audit entity/history; script/worker failure; lost circuit. Test both direct links and nav presentation; server authorization remains authoritative. + +**G2 candidate gate:** full relevant test pass, route-family screenshot review, complete browser modal and dirty-navigation evidence, package version/digest recorded, no duplicate theme/token ownership. Report two-pilot overlay findings to the shared Theme owner before any generic extraction. No new DB schema; test migration is completed in GB before these UI tasks. + +**Later authorized rollout:** Theme artifact availability → isolated dev fixture → one BTDB consumer environment under its existing release procedure, then other environments with observed checks. This is ordering guidance, not deployment authorization or a command to write real batches. Use existing build.sh unchanged; record artifact/version and old application artifact before rollout. Protect active dirty sessions before restart. + +**Rollback:** revert consumer UI commits and Theme pin to the recorded 0.4.1 baseline together if a compatibility problem occurs, restore previous app artifact through normal release process, preserve underlying data/audit/schema. Do not delete pending production records, history, user browser preferences or machine time zones. Keep guard/circuit copy honest about unpersisted drafts. Reproduce the defect on fixture and document remaining gate; source-only unknowns are verification items, not a reason to leave the plan incomplete. diff --git a/docs/plans/2026-11-12-scada-ui-consistency/BUnit.md b/docs/plans/2026-11-12-scada-ui-consistency/BUnit.md new file mode 100644 index 0000000..356b5ca --- /dev/null +++ b/docs/plans/2026-11-12-scada-ui-consistency/BUnit.md @@ -0,0 +1,223 @@ +# bUnit 2.7.2 Standardization Implementation Plan + +> **For Codex:** REQUIRED SUB-SKILL: Use `executeplan` to implement this plan task-by-task. + +**Goal:** Standardize every existing bUnit test project on stable bUnit **2.7.2**, migrate its test API and prove dependency/runtime compatibility before any Theme or application UI implementation. + +**Architecture:** Upgrade test dependencies in their current repository-owned version files and migrate tests in small commits, retaining each repository's xUnit generation, runtime, production packages and behavioral assertions. Establish a shared compatibility record, then close a mandatory cross-repository gate **GB**. Do not introduce bUnit into projects using HtmlRenderer, native Perspective or Playwright alone. + +**Tech Stack:** .NET 10, bUnit 2.7.2, existing xUnit v2/v3 runners and test SDKs, AngleSharp/Css/Diffing, existing JSInterop/auth/navigation fakes and repository test fixtures. + +--- + +## Order, inventory and scope + +Execute this chapter after G0 inventory and **before TH-01, every shared UI task and every local UI task**. GB is the prerequisite for the whole remaining plan, including Secrets target isolation. Baseline discovery is allowed before GB; UI implementation is not. Package/test changes here ship as test-only commits, without Theme publication or application deployment. + +[Source/package inventory](bunit-inventory.json) records seven actual test projects. Its `obj/project.assets.json` observations are cached local evidence, not fresh restores or passing runs. Re-discover all authored `.csproj`, `.props`, `.targets`, lock files and conditional/central package references before execution; exclude hidden worktrees/build outputs. Add newly discovered bUnit consumers to this chapter and the ledger before closing GB. + +| Project | Current bUnit declaration | Version authority | Migration task | +|---|---|---|---| +| Theme | 2.7.2 | `scadaproj/ZB.MOM.WW.Theme/Directory.Packages.props` | BU-03: retain pin, verify graph/runtime | +| ScadaBridge CentralUI.Tests | 2.7.2 | `ScadaBridge/Directory.Packages.props` | BU-04: retain pin, resolve parser policy/runtime | +| Secrets.Ui.Tests | 1.40.0 | `scadaproj/ZB.MOM.WW.Secrets/Directory.Packages.props` | BU-05 | +| Overview.Tests | 1.40.0 | Test `.csproj` | BU-06 | +| OtOpcUa AdminUI.Tests | 2.0.33-preview | `OtOpcUa/Directory.Packages.props` | BU-07 | +| HistorianGateway.Tests | 1.40.0 | Test `.csproj` | BU-08 | +| BTDB Manager.Tests | 1.40.0 | Test `.csproj`; no central package management | BU-09 | + +All paths in the table expand under `/Users/dohertj2/Desktop/`. The exact test project paths and runner versions are in the inventory and task commands below. Preserve OtOpcUa's xUnit v3/Akka TestKit stack and the other projects' xUnit v2 stacks. A central package edit can affect other tests: restore/build those affected projects as part of verification. + +MxAccessGateway, OEE router static-renderer tests, registry Playwright tests and native Perspective remain on their existing test approaches. Their subsequent UI work still waits for GB so the entire family starts Theme implementation from a verified common bUnit baseline. + +## Compatibility decisions and stop conditions + +1. Pin `bunit` **exactly 2.7.2** in each current authority; no floating range, preview, local shim, second bUnit generation, or fallback to a newer unrequested version. Remove direct `bunit.core`/`bunit.web` references only if discovery finds them; check third-party test helpers for old transitive bUnit dependencies. +2. Inspect the **actual restored** `project.assets.json` and nuspecs, including dependency groups for net10.0, AngleSharp, AngleSharp.Css/Diffing, Microsoft.AspNetCore.Components.*, test SDK and runner. The cached bUnit 2.7.2 nuspec declares AngleSharp minimum 1.4.0, Css beta.157 and Diffing 1.1.1; that does not prove patched-parser compatibility. +3. Prefer the already-declared patched AngleSharp 1.5.2 candidate; also probe 1.5.0 where existing Theme evidence uses it. Record the tested exact supported parser version per project; use a common patched version if all full graphs support it. Parser patch uniformity is desirable, but the hard requirement is bUnit 2.7.2 plus a demonstrated compatible and acceptable dependency graph. +4. Secrets currently has a central AngleSharp version declaration without a direct UI-test reference; its cached UI graph still resolves 1.2.0. A `PackageVersion` alone is not a direct dependency. Plan an explicit test-only reference if needed. Add the central parser version plus test-only reference in OtOpcUa/ScadaBridge if the validated combination requires it; do not put parser dependencies in production projects. +5. Existing ScadaBridge/OtOpcUa comments report patched-parser binary failures and scoped GHSA suppression; Theme notes claim a patched combination works. Treat both as hypotheses until **render/query/event tests execute** against the resolved binaries. Compilation, restore or matching version strings do not resolve this disagreement. +6. Run existing NuGet vulnerability/transitive checks without setting `NuGetAudit=false`, adding broad NoWarn or expanding suppressions. Remove the old advisory suppression only after the resolved graph and runtime evidence support removal. If bUnit 2.7.2 cannot meet both runtime compatibility and accepted dependency policy, keep GB incomplete with the exact failing versions/stack trace and a concrete compatibility decision for the owner. Do not silently choose a vulnerable downgrade, a different bUnit version or skip the failing tests to declare success. +7. Do not replace real authorization, renderer dispatch, cancellation, disposal or timing behavior with mocks merely to make the upgrade pass. Keep the separate browser tests for native focus/inertness; bUnit does not prove those behaviors. + +## Migration contract for all later chapters + +The plan's later code snippets now assume this post-GB API. Apply changes to actual repository fixtures during this phase, not by postponing compile fixes to the UI tasks. + +| Previous bUnit API where present | Post-GB API/action | +|---|---| +| `Bunit.TestContext` | `BunitContext`; migrate fixtures and helper signatures | +| `RenderComponent` | `Render` | +| `cut.SetParametersAndRender(...)` | `cut.Render(...)` | +| `AddTestAuthorization()` | `AddAuthorization()`; preserve roles/policies/claims | +| Fake-prefixed bUnit doubles | Corresponding Bunit-prefixed type, including navigation/auth helpers | +| Non-generic rendered fragment/markup abstractions | Appropriate `IRenderedComponent` with actual component/ContainerFragment type | +| `DisposeComponents()` | Await `DisposeComponentsAsync()`; use correct runner lifecycle for async services | +| Event helper optional argument overloads | Explicit event args; keep original event semantics | +| Auto-refreshing element collections | Re-query `FindAll` after render changes | + +These changes follow the [official migration guide](https://bunit.dev/docs/migrations/1to2.html) and [authorization documentation](https://github.com/bunit-dev/bunit/blob/main/docs/site/docs/test-doubles/auth.md). Check the exact 2.7.2 assembly/XML API during execution because current online docs can move forward. **Never globally replace `Xunit.TestContext.Current` in OtOpcUa**: it supplies runner cancellation, not a bUnit renderer. Likewise keep framework `HtmlRenderer.RenderComponentAsync` unchanged. + +## Task BU-01: Record pre-upgrade tests and package graphs + +**Files:** create `/Users/dohertj2/Desktop/scadaproj/components/ui-theme/validation/bunit-2.7.2/BASELINE.md` and per-project result/graph records there; read the seven test projects and their version files in `bunit-inventory.json`. + +1. Record HEAD, SDK, test project, target framework and existing dirty changes per repository. Do not overwrite current work. Locate global/aliased imports, helper base classes, rendered-type signatures and authorization/JSInterop doubles. +2. From each project root run `dotnet restore ` and `dotnet list package --include-transitive`. Record actual resolved versions and relevant audit/suppression context. Use configured approved public/private sources; do not log credentials or proprietary feed headers. +3. Run `dotnet test -c Release --list-tests` and `dotnet test -c Release --logger "trx;LogFileName=before.trx" --results-directory `. Use the exact project paths in BU-03–09. Record discovery count, passed/failed/skipped totals, skipped reasons and pre-existing failures. +4. Mark SQL/Windows/native/live fixtures separately and provision disposable required fixtures for execution where available. Missing infrastructure is not an upgrade regression or a passing test; unverified affected behavior remains an explicit gate item. +5. Commit inventory/baseline evidence only, excluding secrets, runtime data, generated bin/obj and unrelated changes. Expected: a reproducible before record for all seven projects and a list of active migration sites. No test suite is claimed green unless actually run. + +## Task BU-02: Prove the dependency candidate with a minimal render probe + +**Files:** create temporary probes under `/tmp/scada-bunit-compat//`; create the compatibility matrix at `/Users/dohertj2/Desktop/scadaproj/components/ui-theme/validation/bunit-2.7.2/COMPATIBILITY.md`. Final project pins are applied by BU-03–09. + +1. Build a net10.0 xUnit v2 probe with bUnit 2.7.2, a direct candidate AngleSharp reference, the existing Theme test SDK/runner versions, and FrameworkReference Microsoft.AspNetCore.App. Use exact versions, an isolated package directory, and configured approved sources. Do not copy a production configuration or start a service. + Minimal `BunitCompatibility.csproj` for the 1.5.2 candidate (use 1.5.0 only in the separate candidate directory): + + ```xml + + + net10.0 + true + false + enable + enable + + + + + + + + + + + ``` + + Restore each probe with `dotnet restore /tmp/scada-bunit-compat//BunitCompatibility.csproj --packages /tmp/scada-bunit-compat//packages` using a temporary NuGet.Config containing the repository-approved sources, without plaintext credentials. This isolates the dependency resolution from a stale global package directory; retain the resolved assets as probe evidence. + +2. Use this complete runtime probe as one test file (retain existing project global usings or add the imports shown): + + ```csharp + using Bunit; + using Microsoft.AspNetCore.Components; + using Microsoft.AspNetCore.Components.Rendering; + using Xunit; + + public sealed class BunitCompatibilityTests : BunitContext + { + [Fact] + public void Render_query_click_rerender_and_authorization_are_available() + { + var auth = this.AddAuthorization(); + auth.SetAuthorized("synthetic-user"); + auth.SetRoles("Viewer"); + var cut = Render(); + Assert.Equal("Count 0", cut.Find("button").TextContent); + cut.Find("button").Click(); + Assert.Equal("Count 1", cut.Find("button").TextContent); + Assert.Single(cut.FindAll("button")); + } + public sealed class Probe : ComponentBase + { + private int count; + protected override void BuildRenderTree(RenderTreeBuilder b) + { + b.OpenElement(0, "button"); + b.AddAttribute(1, "onclick", EventCallback.Factory.Create(this, () => count++)); + b.AddContent(2, $"Count {count}"); + b.CloseElement(); + } + } + } + ``` + +3. Run `dotnet test /tmp/scada-bunit-compat//BunitCompatibility.csproj -c Release`. First run each candidate against the exact restored graph; expected acceptance is discovery plus successful render/query/event/rerender without TypeLoadException/MissingMethodException. A failure records actual evidence, not a reason to weaken assertions. The class exercises basic API/runtime availability; real policy evaluation and host-specific helpers are tested in the seven suites. +4. Probe the explicitly relevant 1.5.2 and 1.5.0 candidates, inspecting resolved Css/Diffing and framework groups. Record which exact combination is acceptable before applying pins. A simple probe is necessary but not sufficient: each real project migration must pass its own tests. +5. Record any required parser pin as `ANGLESHARP_VERSION` resolved to an actual tested version during execution. If no acceptable combination works, retain the exact bUnit target and leave GB blocked; document follow-up rather than claiming compatibility. No new production dependencies are introduced. + +## Shared steps for each project migration + +Execute these steps separately in BU-03–09, using that task's files, commands and focused suites: + +1. Apply exact bUnit/parser pins in the listed authority, then restore and build the test project. For a 1.x/preview project, capture the compile/API errors as the expected migration red state; for an already-2.7.2 project use the actual runtime/graph baseline instead of inventing a failing test. +2. Migrate the discovered API sites, helpers, inherited contexts, auth doubles, rerenders and disposals according to the table above. Preserve all assertions and role/clock/JSInterop fixtures. Retain strict JSInterop; register only the module/invocations actually needed by existing components. +3. Execute existing render, auth, event, async wait/disposal and representative domain tests before running the full project. If async services require disposal, use the runner's actual v2/v3 lifecycle signatures; do not block on async disposal or declare it complete without awaiting it. +4. Run the full project, compare discovered/executed/skipped results to BU-01, inspect resolved packages and test output. No removed tests, blanket skips, disabled warning policies, deleted behavioral assertions or new arbitrary delays are allowed as migration fixes. +5. Run affected neighboring tests/builds when a central pin or shared helper changed. Record actual runtime-dependent suites separately, including what fixtures are required to close them. +6. Record after graph/TRX and commit test dependencies/tests/docs only, one repository/project slice per commit. Leave production UI and Theme release versions unchanged. Keep the previous complete dependency/test commit for rollback; do not mix old helper binaries with the new package. + +## Task BU-03: Verify Theme's existing stable baseline + +**Cwd:** `/Users/dohertj2/Desktop/scadaproj/ZB.MOM.WW.Theme`. +**Files:** `Directory.Packages.props`; `tests/ZB.MOM.WW.Theme.Tests/ZB.MOM.WW.Theme.Tests.csproj`; existing test fixtures under `tests/ZB.MOM.WW.Theme.Tests/`. + +Follow the shared migration steps: retain bUnit 2.7.2; verify the parser direct reference resolves the chosen patched candidate. Run `dotnet test tests/ZB.MOM.WW.Theme.Tests/ZB.MOM.WW.Theme.Tests.csproj -c Release --filter 'FullyQualifiedName~CommonControlsTests|FullyQualifiedName~ThemeShellTests|FullyQualifiedName~TechButtonExtensionsTests|FullyQualifiedName~TreeTableTests'`, then the full project. Expected: render/query/event/class/disabled/tree behavior stays green with no binary parser errors. Record the exact graph; existing documentation is not evidence of this run. Commit `test(theme): verify standard bUnit dependency baseline` if pins/docs actually change; otherwise record a verification-only evidence commit. + +## Task BU-04: Verify ScadaBridge 2.7.2 and reconcile its parser suppression + +**Cwd:** `/Users/dohertj2/Desktop/ScadaBridge`. +**Files:** `Directory.Packages.props`; `tests/ZB.MOM.WW.ScadaBridge.CentralUI.Tests/ZB.MOM.WW.ScadaBridge.CentralUI.Tests.csproj`; test fixture/helper files beneath that test directory. + +Retain bUnit 2.7.2. The current graph/suppression is specifically part of this task: evaluate the patched candidate with actual runtime renders; add a direct test-only parser reference if necessary, using central management. Update historical incompatibility comments only after evidence; do not erase the warning by disabling audit. Run `dotnet test tests/ZB.MOM.WW.ScadaBridge.CentralUI.Tests/ZB.MOM.WW.ScadaBridge.CentralUI.Tests.csproj -c Release --filter 'FullyQualifiedName~ComponentRenderingTests|FullyQualifiedName~DataConnectionFormTests|FullyQualifiedName~TopologyPageTests'`, then the full project and affected dependency suites. Retain current BunitContext/Render and test doubles where already migrated. Commit `test(scadabridge): validate bUnit parser and render compatibility`. + +## Task BU-05: Upgrade Secrets UI tests and enforce its real parser reference + +**Cwd:** `/Users/dohertj2/Desktop/scadaproj/ZB.MOM.WW.Secrets`. +**Files:** `Directory.Packages.props`; `tests/ZB.MOM.WW.Secrets.Ui.Tests/ZB.MOM.WW.Secrets.Ui.Tests.csproj`; all eight current UI test fixture files (SecretEditorTests, SecretEditorAddExistingTests, SecretsListTests, ConfirmDeleteModalTests, RevealButtonTests, ComponentAuthorizationTests, RevealAuditFailureTests, AuditFailureAfterCommitTests). + +Set central bUnit to 2.7.2. Add an explicit `` to the UI test project if needed so its selected central version is actually consumed; a central entry alone previously left cached 1.2.0. Migrate BunitContext/Render/AddAuthorization and helper signatures, including callback-driven rerenders and context disposal. Run `dotnet test tests/ZB.MOM.WW.Secrets.Ui.Tests/ZB.MOM.WW.Secrets.Ui.Tests.csproj -c Release --filter 'FullyQualifiedName~ComponentAuthorizationTests|FullyQualifiedName~SecretEditorTests|FullyQualifiedName~RevealAuditFailureTests|FullyQualifiedName~AuditFailureAfterCommitTests'`, then the full UI test project and tests affected by the central change. Expected: audit-before-reveal, success-after-commit/audit-failure and handler authorization remain unchanged. Commit `test(secrets): migrate UI suites to bUnit 2.7.2`. + +## Task BU-06: Upgrade Overview tests and preserve timer lifecycle assertions + +**Cwd:** `/Users/dohertj2/Desktop/scadaproj/ZB.MOM.WW.Overview`. +**Files:** `tests/ZB.MOM.WW.Overview.Tests/ZB.MOM.WW.Overview.Tests.csproj`; `InstanceCardTests.cs`, `OverviewPageTests.cs` in that test directory; its global using/helper declarations if affected. + +Pin bUnit 2.7.2 directly; retain/validate the patched parser pin using BU-02. Migrate TestContext/RenderComponent and shared render helper return types; preserve fake clock, store publication, synchronization and disposal behavior. Run `dotnet test tests/ZB.MOM.WW.Overview.Tests/ZB.MOM.WW.Overview.Tests.csproj -c Release --filter 'FullyQualifiedName~InstanceCardTests|FullyQualifiedName~OverviewPageTests'`, then the full project including boot/probe tests. Expected: pause/adopt/resume, stale aging and event unsubscription assertions stay green without adding sleeps. Commit `test(overview): migrate renderer fixtures to bUnit 2.7.2`. + +## Task BU-07: Replace OtOpcUa's preview while preserving xUnit v3 cancellation + +**Cwd:** `/Users/dohertj2/Desktop/OtOpcUa`. +**Files:** `Directory.Packages.props`; `tests/Server/ZB.MOM.WW.OtOpcUa.AdminUI.Tests/ZB.MOM.WW.OtOpcUa.AdminUI.Tests.csproj`; discovered bUnit fixtures under that directory, especially `Pages/DeleteConfirmRenderTests.cs` and renderer/auth helpers. + +Replace preview 2.0.33 with exactly 2.7.2. Add a central/direct test-only parser pin if validated; revisit the TypeLoadException explanation and scoped advisory suppression using evidence. Current BunitContext/Render use reduces rename work but does not establish compatibility with stable release. Preserve xunit.v3 3.2.2, its runner and Akka.TestKit.Xunit: **Xunit.TestContext.Current.CancellationToken stays unchanged**. Migrate only bUnit authorization/double/obsolete APIs found by discovery. Run `dotnet test tests/Server/ZB.MOM.WW.OtOpcUa.AdminUI.Tests/ZB.MOM.WW.OtOpcUa.AdminUI.Tests.csproj -c Release --filter FullyQualifiedName~DeleteConfirmRenderTests`, then the full AdminUI test project; classify SQL fixture prerequisites explicitly. Run affected central-package consumers once. Expected: real delete confirmation, authorization, event dispatch and cancellation regressions remain protected. Commit `test(otopcua): replace bUnit preview with 2.7.2`. + +## Task BU-08: Upgrade HistorianGateway dashboard fixtures + +**Cwd:** `/Users/dohertj2/Desktop/HistorianGateway`. +**Files:** `tests/ZB.MOM.WW.HistorianGateway.Tests/ZB.MOM.WW.HistorianGateway.Tests.csproj`; dashboard fixtures `GalaxyBrowserPageRenderTests.cs`, `StatusPageRenderTests.cs`, `HealthPageRenderTests.cs`, `HistorianConsolePageRenderTests.cs`, `LayoutRenderTests.cs`, `ApiKeysPageRenderTests.cs`, `LayoutNavAuthorizationTests.cs` under `Dashboard/`. + +Pin bUnit 2.7.2 and validated parser dependency in this test project; migrate contexts/render/auth/doubles and any async lifetime handling. Keep test-only framework references supporting rendered components. Run `dotnet test tests/ZB.MOM.WW.HistorianGateway.Tests/ZB.MOM.WW.HistorianGateway.Tests.csproj -c Release --filter FullyQualifiedName~Dashboard`, then the full project. Expected: Viewer/Admin gating, history query payloads and write gating still pass; no real historian write is required. Preserve native/Windows fixture distinctions. Commit `test(historiangateway): migrate dashboard tests to bUnit 2.7.2`. + +## Task BU-09: Upgrade BTDB fixture helpers and navigation/auth doubles + +**Cwd:** `/Users/dohertj2/Desktop/BTDB`. +**Files:** `tests/ZB.MOM.WW.BTDB.Manager.Tests/ZB.MOM.WW.BTDB.Manager.Tests.csproj`; helpers `Auth/RealPolicyAuthorization.cs`, `Shared/AuthorizeTestHelper.cs`; bUnit fixtures beneath `Layout/`, `Shared/`, `Pages/` discovered by BU-01. + +Pin bUnit 2.7.2 directly; no new central package-management file. Validate parser pin; migrate TestContext/RenderComponent/auth helpers and FakeNavigationManager types where actually used. Preserve real policy registration rather than replacing it with unconditional authorization. Run `dotnet test tests/ZB.MOM.WW.BTDB.Manager.Tests/ZB.MOM.WW.BTDB.Manager.Tests.csproj -c Release --filter 'FullyQualifiedName~MachineFormTests|FullyQualifiedName~DialogServiceTests|FullyQualifiedName~EditableRowsTests|FullyQualifiedName~MainLayoutRailTests'`, then the full Manager test project and existing Manager.Core tests. Expected: Cancel rollback, row snapshot identity, full timestamp precision, role gates and host boot regressions stay covered. Do not alter navigation production code in this migration. Commit `test(btdb): migrate component fixtures to bUnit 2.7.2`. + +## Task BU-10: Verify cross-project consistency and close GB + +**Files:** update compatibility/baseline records and add `/Users/dohertj2/Desktop/scadaproj/components/ui-theme/validation/bunit-2.7.2/ACCEPTANCE.md`; add the same actual package/commit/TRX references to each repository's relevant test documentation. Update stale bUnit/parser comments and test examples; runtime UI recommendations remain historical evidence. + +1. Re-discover authored bUnit consumers and assert the set matches the recorded inventory. Use `dotnet list package --include-transitive` and resolved assets to prove **all seven resolve bunit/2.7.2** with no legacy core/web generation. Central declarations alone do not prove this. +2. Run each migrated test project in Release from a clean restore against approved configured sources, with a fresh test output directory. Preserve vulnerability checks. Verify parser/Css/Diffing/framework/runner versions match the accepted matrix and the same assembly versions actually load at render runtime. +3. Compare before/after discovery and TRX by test identity, passed/failed/skipped totals and reasons. A parameterized-test count change must be explained rather than mistaken for missing coverage. No unexplained loss, new blanket skip, weakened assertion, binary load error or hang may remain. +4. Exercise the representative runtime contracts: render/query/click/rerender; allowed/denied role/policy; strict JSInterop; async completion/waits; cancellation; context/component/service disposal. Use synthetic fixtures; no production mutation. Run impacted non-bUnit suites only as warranted by central/shared changes. +5. Inspect release/publish graphs: bUnit, AngleSharp test pins and xUnit must not newly enter production package/runtime dependencies. Archive actual package versions, warnings/advisory disposition, source commits and test evidence; exclude real secrets and generated build trees. +6. Close **GB only after every bUnit project and its required affected behavior is verified**. Missing fixture/infrastructure or dependency-policy incompatibility leaves the exact check incomplete and blocks Theme/UI execution; record the required next action. Do not lower the bUnit target or bypass this gate because two projects were already on it. +7. Commit `docs(testing): record family bUnit 2.7.2 acceptance`. Then execute the original Theme-first UI sequence unchanged in design scope. + +## Rollback and completion + +This phase changes test dependencies, fixtures/helpers and their documentation only. Roll back a failed slice as one coherent test/dependency commit, retaining the prior graph and evidence; do not restore a single DLL, publish a downgraded Theme, mutate data or revert unrelated production code. If any project returns to an old bUnit version, reopen GB. Later UI chapters must not silently reintroduce old APIs or package versions. + +- [ ] Seven projects freshly resolve exact stable 2.7.2, including existing adopters and OtOpcUa preview replacement. +- [ ] AngleSharp family and .NET/test-runner compatibility verified by actual runtime tests and acceptable audit policy. +- [ ] All applicable existing tests migrated with behavior and discovery preserved; explicit results for environment-dependent checks. +- [ ] Async lifecycle and auth/navigation/JSInterop behavior validated without broad mocks/suppression/skips. +- [ ] Later plan snippets use BunitContext/Render/AddAuthorization; framework HtmlRenderer and Xunit.TestContext remain untouched. +- [ ] GB evidence recorded before any Theme or application UI task begins. + +No upgrade or test execution occurs while writing this plan. Expected results above are future acceptance criteria. diff --git a/docs/plans/2026-11-12-scada-ui-consistency/EXECUTION.md b/docs/plans/2026-11-12-scada-ui-consistency/EXECUTION.md new file mode 100644 index 0000000..4e58a10 --- /dev/null +++ b/docs/plans/2026-11-12-scada-ui-consistency/EXECUTION.md @@ -0,0 +1,21 @@ +# Execution checkpoint — November 13, 2026 + +Active objective: execute all 100 plan tasks, with all seven bUnit projects verified before any Theme/UI updates. This checkpoint is partial progress, not completion. + +Worktree: `/Users/dohertj2/.codex/worktrees/scada-ui-consistency/scadaproj`; branch `codex/scada-ui-consistency`; source base `9c3ab5f`. + +| Project | Fresh before | After 2.7.2 / parser 1.5.2 | State | +|---|---|---|---| +| Theme | 70 pass | 70 pass | verified | +| Secrets UI | 34 pass | 34 pass | verified, clean-output confirmation | +| Overview | 197 pass | 197 pass | verified, clean-output confirmation | +| ScadaBridge | not run | not run | managed worktree pending | +| OtOpcUa | not run | not run | managed worktree pending | +| HistorianGateway | not run | not run | managed worktree pending | +| BTDB | not run | not run | managed worktree pending | + +All three verified projects retain exact test identities/outcomes, zero failures/skips, clean transitive vulnerability reports and no production test-package leakage. Changes are test-only dependencies and fixture API migration. No Theme component/CSS/public API or app UI source was changed. + +Parent pending worktree batch: functions cell `g4:77`. Agent pending cells: ScadaBridge `g6:41`, OtOpcUa `g6:43`, HistorianGateway `g7:39`. Calls are yielded/live, not reported as terminal errors. No corresponding sister worktrees or Git worktree-creation process were observed in the last read-only check. Do not duplicate/restart based solely on elapsed time. Poll these handles or inspect returned operation IDs if they arrive. The parent wrapper may report an already-existing branch/copy destination after worktree calls complete; those root setup operations were safely completed while the calls were pending. + +GB remains OPEN. Do not start TH-01 or other shared/app UI tasks. Continue the four isolated migrations after real paths arrive; then close BU-01/BU-10 using fresh runtime evidence. Evidence: `components/ui-theme/validation/bunit-2.7.2/`. diff --git a/docs/plans/2026-11-12-scada-ui-consistency/HistorianGateway.md b/docs/plans/2026-11-12-scada-ui-consistency/HistorianGateway.md new file mode 100644 index 0000000..5d60785 --- /dev/null +++ b/docs/plans/2026-11-12-scada-ui-consistency/HistorianGateway.md @@ -0,0 +1,369 @@ +# HistorianGateway UI consistency Implementation Plan + +> **For Codex:** REQUIRED SUB-SKILL: Use `executeplan` to implement this plan task-by-task. + +**Goal:** Make historical queries, manual status freshness and diagnostic-write intent clear and accessible within the shared Technical-Light system. + +**Architecture:** Retain the existing shared shell and green product accent while adopting G1 semantic ink, field associations and state patterns. Keep point-in-time status, read-only Galaxy metadata and administrator diagnostic writes as separate domain responsibilities; no historian protocol or storage mutation is added by theme adoption. + +**Tech Stack:** net10.0 Blazor InteractiveServer, Bootstrap CSS, Theme currently 0.5.0, xUnit 2.9.3, bUnit 2.7.2 after GB, GB-validated AngleSharp dependency graph. + +--- + +## 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. + +## Execution contract + +- Repository: `/Users/dohertj2/Desktop/HistorianGateway`. All source/test paths below are relative to that root; use it as cwd unless a step states otherwise. +- Planning date: 2026-11-12. This chapter specifies future work; no implementation or test execution is claimed. +- Read the corresponding `/Users/dohertj2/Desktop/scadaproj/impeccable/HistorianGateway.md`, the shared design-system report, the master plan and applicable `AGENTS.md` before execution. +- Reuse a suitable checkout; inspect `git status --short` and preserve user edits. No new worktree, commit, push, package publication or deployment is performed by authoring this plan. +- **Dependency gate:** complete shared Theme G1 compatibility audit, assign `THEME_VERSION`, and verify its artifact before consumer migration. `THEME_VERSION` is a placeholder, never a literal package version to publish. +- Shared G1 supplies semantic status ink (`--ok-ink:#236f34`, `--warn-ink:#855000`, `--bad-ink:#b42121`, `--idle-ink:#535d66`), `--ink-faint:#626970`, and independent blue `--info-ink`; product accent never recolors semantic informational notices. +- G1 adds `TechField.For`, `HintId`, `ErrorId`; callers supply input IDs, `aria-describedby` and `aria-invalid`. G1 adds `ThemeShell.AccentDeep`, `AccentTint`, `AccentBorder`, `AccentFocus` while preserving `Accent`. +- Shared accent aliases must resolve in shell scope: G1 uses `--accent-tint` directly or rebinds inherited aliases at `.app-shell`. Bootstrap `.btn-primary`/ghost component variables must follow shell accent for normal/hover/active/disabled states. Compare computed states before deleting any consumer override. +- G1 also supplies shared focus/busy/reduced-motion and filter/table/dialog recipes. `TechButton.BusyText` is optional; busy adds `aria-busy`. Caller-owned status/alert text announces outcomes, never secret values or every polling update. +- Pilot native dialogs in two consumers before extracting a common dialog component. Do not build a new component package during a first consumer migration. +- Restore/build first and record actual dependency/runtime failures. Complete GB bUnit/parser standardization first. Preserve xUnit, test SDK and Playwright versions unless a specific demonstrated compatibility fix is recorded in GB; do not perform later incidental framework upgrades. Never treat a skipped native/SQL/COM/live test as a pass. +- Each numbered step is one short action. When a step discovers broader product behavior, stop that task at its boundary and update this written plan before expanding implementation scope. + +## Verified baseline and package gate + +- `src/ZB.MOM.WW.HistorianGateway.Server/ZB.MOM.WW.HistorianGateway.Server.csproj:30` directly pins Theme 0.5.0; Secrets/Secrets.Ui pin 0.6.2. Compare transitive Theme graphs before assigning `SECRETS_UI_VERSION` and `THEME_VERSION`. +- Existing bUnit helpers/fakes live in `tests/ZB.MOM.WW.HistorianGateway.Tests/Dashboard/`. The snippets below are **additions inside the named existing class**, with its current imports, fake and `BunitContext` base. +- The pre-GB test project pins bUnit 1.40.0 and AngleSharp 1.5.2; BU-08 replaces that baseline with verified bUnit 2.7.2 and its accepted parser graph. Run the post-GB baseline before UI edits; investigate dependency regressions without undoing the standardization. +- `IDashboardStatusService` normally catches connectivity-probe failures and returns an Unreachable verdict. HG-02 handles an unexpected page retrieval failure separately; never replace a valid Unreachable snapshot with a generic exception state. +- Baseline commands from repo root: `dotnet restore src/ZB.MOM.WW.HistorianGateway.Server/ZB.MOM.WW.HistorianGateway.Server.csproj`; `dotnet list src/ZB.MOM.WW.HistorianGateway.Server/ZB.MOM.WW.HistorianGateway.Server.csproj package --include-transitive`; focused Dashboard tests below. +- Preserve green product accent `#2f855a`. Set its new deep/tint/border/focus family only to values approved in G1; semantic Info remains blue through `--info-ink`. + +## Findings coverage + +| Report finding | Planned task | Primary proof | +| --- | --- | --- | +| HG-01 unassociated labels | HG-01 | Every visible console control has associated label | +| HG-02 freshness/stale retrieval | HG-02 | Sequential status fake + manual-refresh header | +| HG-03 hover-only diagnostics | HG-03 | Expandable full safe text on health/member rows | +| HG-04 write intent review | HG-04 | No write before confirm; cancel makes zero calls | +| HG-05 search/toggle names | HG-05 | Named controls, retained lazy rendering and 300 hit cap | +| HG-06 query context/feedback | HG-06 | Submitted request retained independently of edited next request | +| HG-07 landing signposts | HG-07 | Task-oriented links, no duplicate status or new polling | + +### G1 asset adoption before HG-01 + +1. After G1 compatibility audit resolves `THEME_VERSION`, update only the explicit Theme reference in Server.csproj; update Secrets.Ui only if its compatible verified release is required. +2. Restore and compare the transitive graph; confirm no downgrade/unintended floating reference. +3. Build Server, rerun baseline dashboard tests, and check fonts/Theme CSS load in a local browser fixture. +4. In `Dashboard/Components/Layout/MainLayout.razor`, preserve the existing green Accent and supply matching optional accent family from G1; check focus/selection/hover in the actual shell. +5. Keep `wwwroot/css/site.css` domain geometry; remove a local rule only after proving G1 supplies equivalent behavior. Separate semantic ink from status fill swatches. +6. Record the exact package graph and screenshot comparison in `docs/ui-validation/technical-light-historian.md`; commit this isolated adoption as `style: adopt shared Historian theme contract`. + +## HG-01: Associate all history and diagnostic fields + +**Files:** + +- Modify `src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/HistorianConsolePage.razor` +- Modify `tests/ZB.MOM.WW.HistorianGateway.Tests/Dashboard/HistorianConsolePageRenderTests.cs` + +**Step 1 — Establish the failing behavior.** Add the following test inside HistorianConsolePageRenderTests. The fake and Viewer authorization idiom already exist. Add a second case for Administrator to cover diagnostic input labels. + +```csharp +[Fact] +public void Query_inputs_have_programmatically_associated_labels() +{ + var auth = this.AddAuthorization(); + auth.SetAuthorized("viewer"); + auth.SetRoles(DashboardRoles.Viewer); + Services.AddSingleton(new FakeDashboardHistorianService()); + var cut = Render(); + foreach (var control in cut.FindAll("input, select")) + { + var id = control.Id; + Assert.False(string.IsNullOrWhiteSpace(id)); + Assert.NotEmpty(cut.FindAll($"label[for='{id}']")); + } +} +``` + +**Step 2 — Run the focused check.** From the repository root: + +```bash +dotnet test tests/ZB.MOM.WW.HistorianGateway.Tests/ZB.MOM.WW.HistorianGateway.Tests.csproj --filter FullyQualifiedName~HistorianConsolePageRenderTests +``` + +Expected before: query inputs have no stable IDs with matching labels. + +**Step 3 — Implement in small edits.** + +1. Assign stable distinct IDs for query-tag/mode/max-values/start/end/retrieval/interval and every value/event write field. +2. Apply TechField.For only where the wrapper helps; ensure caller input IDs and describedby/invalid attributes remain explicit. +3. Use fieldsets/legends for related date range and write operation; associate hint/error IDs and keep UTC visible in labels. +4. Keep current query and server role behavior; do not introduce a second validation model. + +**Step 4 — Verify the change.** Re-run Step 2; expected after: PASS for the named tests or all stated visual checks. Click labels in browser and verify focus moves to the intended field. Tab through both raw/aggregate layouts and Admin write fields; each name stays unambiguous after mode changes. + +**Step 5 — Commit.** Stage only the listed production/test/evidence files, inspect `git diff --cached`, then `git commit -m "fix: associate Historian console form labels"`. Do not include generated credentials, runtime data or unrelated edits. + +## HG-02: Show sampled time and recover unexpected refresh failures + +**Files:** + +- Modify `src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/StatusPage.razor` +- Modify `src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/HealthPage.razor` +- Modify `tests/ZB.MOM.WW.HistorianGateway.Tests/Dashboard/StatusPageRenderTests.cs` +- Modify `tests/ZB.MOM.WW.HistorianGateway.Tests/Dashboard/HealthPageRenderTests.cs` + +**Step 1 — Establish the failing behavior.** Add a sequence fake inside StatusPageRenderTests. Use BaseStatus() already in that file. First render succeeds, then refresh throws, proving the last snapshot and visible stale state survive independently of the ordinary Unreachable verdict. + +```csharp +private sealed class SucceedsThenFails(DashboardStatus first) : IDashboardStatusService +{ + private int calls; + public Task GetStatusAsync(CancellationToken cancellationToken = default) + => ++calls == 1 ? Task.FromResult(first) + : Task.FromException(new IOException("fixture unavailable")); +} +[Fact] +public void Refresh_failure_retains_the_last_good_snapshot_and_marks_it_stale() +{ + Services.AddSingleton(new SucceedsThenFails(BaseStatus())); + var cut = Render(); + cut.Find("button").Click(); + cut.WaitForAssertion(() => { + Assert.Contains("hist01:32565", cut.Markup); + Assert.NotEmpty(cut.FindAll("[data-stale='true']")); + Assert.Contains("Retry", cut.Markup); + }); +} +``` + +**Step 2 — Run the focused check.** From the repository root: + +```bash +dotnet test tests/ZB.MOM.WW.HistorianGateway.Tests/ZB.MOM.WW.HistorianGateway.Tests.csproj --filter FullyQualifiedName~StatusPageRenderTests +``` + +Expected before: an unexpected refresh exception is not handled by the page; no data-stale banner exists. + +**Step 3 — Implement in small edits.** + +1. Put generated time and “Manual refresh” adjacent to page title/status; use actual GeneratedUtc, not render time. +2. Store page-level loading/error state separately from the last successful status/report. Catch expected retrieval exceptions, preserve last-good data, mark it stale and provide Retry. +3. On first-load failure render no-data error recovery, never stale empty values. On valid Unreachable report show its actual sampled state. +4. Add cancellation/disposal protection to prevent a late result changing disposed component state; prevent duplicate refresh while busy. +5. Health has no generated timestamp in HealthReport: record captured time at successful report acquisition using injected TimeProvider, not a fabricated source timestamp. + +**Step 4 — Verify the change.** Re-run Step 2; expected after: PASS for the named tests or all stated visual checks. Check initial failure, slow refresh, successful unreachable report, unexpected refresh failure after success and recovery. Refresh remains manual; no hidden polling is introduced. A real browser verifies one polite outcome announcement and visible retry focus. + +**Step 5 — Commit.** Stage only the listed production/test/evidence files, inspect `git diff --cached`, then `git commit -m "fix: expose Historian snapshot freshness and stale recovery"`. Do not include generated credentials, runtime data or unrelated edits. + +## HG-03: Make health and member detail accessible without hover + +**Files:** + +- Modify `src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/HealthPage.razor` +- Modify `src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/StatusPage.razor` +- Modify `tests/ZB.MOM.WW.HistorianGateway.Tests/Dashboard/HealthPageRenderTests.cs` +- Modify `tests/ZB.MOM.WW.HistorianGateway.Tests/Dashboard/StatusPageRenderTests.cs` + +**Step 1 — Establish the failing behavior.** Extend existing health/member fixture cases with a long safe description. Assert its full text is present within a named details disclosure, not just a title attribute. Seed a deliberately unsafe credential-like string at the service redaction test boundary and verify it is absent before the UI receives data. + +**Step 2 — Run the focused check.** From the repository root: + +```bash +dotnet test tests/ZB.MOM.WW.HistorianGateway.Tests/ZB.MOM.WW.HistorianGateway.Tests.csproj --filter FullyQualifiedName~HealthPageRenderTests +dotnet test tests/ZB.MOM.WW.HistorianGateway.Tests/ZB.MOM.WW.HistorianGateway.Tests.csproj --filter FullyQualifiedName~StatusPageRenderTests +``` + +Expected before: full messages are only exposed through title text and abbreviated visible spans. + +**Step 3 — Implement in small edits.** + +1. Replace tooltip-only full-detail access with an inline native details disclosure per relevant row; use concise summary labels including check/member identity. +2. Preserve table semantics and short scan rows; full details wrap and are copyable. +3. Keep secret removal in service/logging boundaries; UI should never make an unsafe raw exception expandable. Do not broaden returned diagnostic fields. + +**Step 4 — Verify the change.** Re-run Step 2; expected after: PASS for the named tests or all stated visual checks. Tab to a failed health check, open details with Space, read/copy full safe message on touch and keyboard, then close. Confirm a long message only expands its own row and no whole-page horizontal overflow appears. + +**Step 5 — Commit.** Stage only the listed production/test/evidence files, inspect `git diff --cached`, then `git commit -m "fix: expose accessible Historian diagnostic details"`. Do not include generated credentials, runtime data or unrelated edits. + +## HG-04: Review diagnostic writes before dispatch + +**Files:** + +- Modify `src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/HistorianConsolePage.razor` +- Modify `tests/ZB.MOM.WW.HistorianGateway.Tests/Dashboard/HistorianConsolePageRenderTests.cs` + +**Step 1 — Establish the failing behavior.** Replace the old direct-write test expectation with the following Admin test; it uses the existing recording fake. Add cancel and duplicate-submit cases by observing fake call count. These tests intentionally change the UI behavior without changing backend authorization. + +```csharp +[Fact] +public void Historical_insert_waits_for_explicit_confirmation() +{ + var auth = this.AddAuthorization(); + auth.SetAuthorized("admin"); + auth.SetRoles(DashboardRoles.Admin); + var fake = new FakeDashboardHistorianService(); + Services.AddSingleton(fake); + var cut = Render(); + cut.Find("input.console-write-tag").Change("Pump01.PV"); + cut.Find("input.console-write-value").Change("99.9"); + cut.Find("button.console-write-review").Click(); + Assert.Null(fake.LastValueWrite); + Assert.Contains("Pump01.PV", cut.Find("[data-write-review]").TextContent); + cut.Find("button.console-write-confirm").Click(); + Assert.Equal("Pump01.PV", fake.LastValueWrite?.Tag); +} +``` + +**Step 2 — Run the focused check.** From the repository root: + +```bash +dotnet test tests/ZB.MOM.WW.HistorianGateway.Tests/ZB.MOM.WW.HistorianGateway.Tests.csproj --filter FullyQualifiedName~HistorianConsolePageRenderTests +``` + +Expected before: the existing Insert action calls the write service immediately, before a review step. + +**Step 3 — Implement in small edits.** + +1. Keep administrator AuthorizeView and server authorization intact; put diagnostic writes in a clearly labeled disclosure with persisted typed draft. +2. Snapshot the proposed value/event request when Review is chosen; show target, operation, tag, value/event and UTC timestamp. Editing the draft invalidates an earlier pending review. +3. Require explicit Confirm write to call the existing service. Cancel returns to draft with zero writes; busy disables repeated confirm. +4. On failure preserve draft/review context and show safe recovery; success records actual service outcome and clears pending intent so Back/refresh cannot replay it. +5. Use in-page review, not a new modal. Do not add API or historian-client operations, and never exercise real writes during visual validation. + +**Step 4 — Verify the change.** Re-run Step 2; expected after: PASS for the named tests or all stated visual checks. In a fake/local fixture verify Viewer cannot see controls, Admin can review, cancellation sends no write, slow confirm sends exactly one request, and an error retains input. Use actual UTC boundary values and non-numeric input validation; never write to a production historian for UI acceptance. + +**Step 5 — Commit.** Stage only the listed production/test/evidence files, inspect `git diff --cached`, then `git commit -m "feat: review Historian diagnostic write intent"`. Do not include generated credentials, runtime data or unrelated edits. + +## HG-05: Name Galaxy filtering and expansion controls + +**Files:** + +- Modify `src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/GalaxyBrowserPage.razor` +- Modify `src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Shared/GalaxyTreeNodeView.razor` +- Modify `tests/ZB.MOM.WW.HistorianGateway.Tests/Dashboard/GalaxyBrowserPageRenderTests.cs` + +**Step 1 — Establish the failing behavior.** Extend existing Galaxy render tests using their current snapshot fixture: assert persistent search label association and a named Expand [object] control with collapsed state. Keep service result-cap and lazy render tests; do not materialize 42k attributes merely to test a label. + +**Step 2 — Run the focused check.** From the repository root: + +```bash +dotnet test tests/ZB.MOM.WW.HistorianGateway.Tests/ZB.MOM.WW.HistorianGateway.Tests.csproj --filter FullyQualifiedName~GalaxyBrowserPageRenderTests +``` + +Expected before: search is placeholder-only and node buttons have generic Toggle names. + +**Step 3 — Implement in small edits.** + +1. Add visible label and Clear search; derive polite count from the applied search result, including capped-results copy. +2. Make node label and chevron one named button with expanded state; keep stable per-node controls ID and child lazy creation. +3. Preserve read-only metadata semantics: no Watch, write or subscription buttons are added to this gateway. +4. After manual reload preserve current search and expansion keys where objects still exist; avoid full expansion by default. + +**Step 4 — Verify the change.** Re-run Step 2; expected after: PASS for the named tests or all stated visual checks. Keyboard-expand a node, filter to zero, clear and verify contextual state. Load a realistic large fixture and confirm initial rendering is bounded by collapsed roots and the flat search cap remains 300. + +**Step 5 — Commit.** Stage only the listed production/test/evidence files, inspect `git diff --cached`, then `git commit -m "fix: name Historian Galaxy browse controls"`. Do not include generated credentials, runtime data or unrelated edits. + +## HG-06: Keep submitted query context separate from editable draft + +**Files:** + +- Modify `src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/HistorianConsolePage.razor` +- Modify `tests/ZB.MOM.WW.HistorianGateway.Tests/Dashboard/HistorianConsolePageRenderTests.cs` + +**Step 1 — Establish the failing behavior.** Add the following to the existing bUnit class. It protects against silently relabeling old results when a user edits the next query. + +```csharp +[Fact] +public void Editing_the_next_query_does_not_relabel_previous_results() +{ + var auth = this.AddAuthorization(); + auth.SetAuthorized("viewer"); + auth.SetRoles(DashboardRoles.Viewer); + Services.AddSingleton(new FakeDashboardHistorianService()); + var cut = Render(); + cut.Find("input.console-tag").Change("Pump01.PV"); + cut.Find("button.console-run").Click(); + cut.Find("input.console-tag").Change("Pump02.PV"); + var context = cut.Find("[data-submitted-query]").TextContent; + Assert.Contains("Pump01.PV", context); + Assert.DoesNotContain("Pump02.PV", context); +} +``` + +**Step 2 — Run the focused check.** From the repository root: + +```bash +dotnet test tests/ZB.MOM.WW.HistorianGateway.Tests/ZB.MOM.WW.HistorianGateway.Tests.csproj --filter FullyQualifiedName~HistorianConsolePageRenderTests +``` + +Expected before: there is no submitted-query context region; the old result set has only a row count. + +**Step 3 — Implement in small edits.** + +1. Create an immutable submitted query snapshot at dispatch; render tag/range/mode beside returned rows, never bind this heading to the current draft. +2. Name the action Run query and show BusyText/aria-busy according to G1; use one caller-owned outcome status. +3. Render unsuccessful result in a distinct safe alert, successful zero samples with range-adjustment guidance, and keep numeric quality plus explained text where mapping is reliable. +4. Disable duplicate dispatch while running and guard stale completion with request identity if mode/query can change during work; do not introduce parallel historian calls. + +**Step 4 — Verify the change.** Re-run Step 2; expected after: PASS for the named tests or all stated visual checks. Test success, zero rows, invalid range, failed service, slow query and edit-after-success. Keep full numeric quality/source information and UTC context. Confirm ordinary query submission remains one action; write-review behavior stays separate. + +**Step 5 — Commit.** Stage only the listed production/test/evidence files, inspect `git diff --cached`, then `git commit -m "fix: preserve submitted Historian query context"`. Do not include generated credentials, runtime data or unrelated edits. + +## HG-07: Flatten signposts without duplicating status + +**Files:** + +- Modify `src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/Home.razor` +- Modify `src/ZB.MOM.WW.HistorianGateway.Server/wwwroot/css/site.css` +- Update `docs/ui-validation/technical-light-historian.md` + +**Step 1 — Establish the failing behavior.** Capture the current landing page and the concise task-list proposal. This is low-impact composition/copy: use visual and destination checks rather than a test mirroring the DOM layout. + +**Step 2 — Run the focused check.** From the repository root: + +```bash +dotnet build src/ZB.MOM.WW.HistorianGateway.Server/ZB.MOM.WW.HistorianGateway.Server.csproj +``` + +Expected before: the current equal-size panels repeat rail destinations and dilute the read/query/write distinction. + +**Step 3 — Implement in small edits.** + +1. Replace equal-size signpost cards with a grouped task list: inspect status/health, browse metadata, query history. +2. Keep all existing destinations, route names and Admin navigation gates; do not put a new live metric snapshot or polling on Home. +3. Keep compact family typography and spacing; distinguish read-only query entry from administrator-only diagnostic actions. + +**Step 4 — Verify the change.** Re-run Step 2; expected after: PASS for the named tests or all stated visual checks. Check all signposts resolve, each has specific accessible link text, one h1 remains, and no duplicate fetch is introduced. Verify 390px and 200% zoom plus the green shell/blue Info distinction. + +**Step 5 — Commit.** Stage only the listed production/test/evidence files, inspect `git diff --cached`, then `git commit -m "style: simplify Historian landing task navigation"`. Do not include generated credentials, runtime data or unrelated edits. + +## Cross-cutting state and viewport matrix + +| State | Expected contract | Verification | +| --- | --- | --- | +| First load / slow work | Page identity remains; busy action disabled with meaningful busy text; no false successful zero | Delayed fixture and keyboard | +| Healthy | Text label plus status token, sampled time, real scope | Representative fixture | +| Warning / failed dependency | Plain summary, affected scope and recovery; safe detail disclosure | Fault fixture; no raw secret/connection string | +| Refresh fails after success | Keep last good data visibly marked stale; retry does not clear context | Sequential success/failure fake | +| Empty / no matches | Different from loading/failure; clear-filter or next action | Empty source and filtered-to-zero separately | +| Unavailable / unknown | Show unknown/n/a, never substitute numeric zero or Healthy | Null/missing fixture | +| Permission denied | Route and action gates remain server-enforced; nav reflects existing policy | Viewer/Admin/denied accounts | +| Long content | Full identifiers available in detail/copy context; table scroll local | 200-character path and error | +| Keyboard / modal | Visible focus; enter/space activation; real modal inertness and focus restoration | Browser test, not HtmlRenderer | +| Narrow / zoom / motion | 1440×900, 1024×768, 390×844, 200% zoom; reduced motion keeps status feedback | Batched visual pass and at most one confirmation pass | + +No runtime timestamps or status values in a mockup are deployment evidence. Keep status domain mapping app-owned. Test color contrast against actual computed backgrounds; screenshots alone do not establish WCAG compliance. + +## Release and rollback + +1. Run focused dashboard tests with `dotnet test tests/ZB.MOM.WW.HistorianGateway.Tests/ZB.MOM.WW.HistorianGateway.Tests.csproj --filter FullyQualifiedName~Dashboard`; then run the full project once. Keep all existing role, service redaction and write-gating tests. +2. Build Server and validate CSS/font/module fetches in an isolated host with fake historian responses. macOS cannot establish Windows AVEVA/COM runtime acceptance; record Windows/native integration tests as outstanding unless actually executed. +3. No diagnostic write is required against a real historian for this UI release. Use fakes to verify dispatch payload/count, then separate owner-approved runtime validation if needed. +4. Save package graph, shared artifact checksum/version, commit IDs, before/after captures, contrast values and completed keyboard/state matrix to the validation record. Redact tokens and connection details from evidence. +5. Deploy only through the existing repository release process as a separate authorized action. Changes have no DB/proto/store-forward schema impact. +6. Roll back coherently by reverting consumer UI commits and restoring the former package graph (Theme currently 0.5.0, Secrets.Ui currently 0.6.2). Re-run query, Viewer/Admin gating and native status checks. Do not downgrade stored historian values or delete an outbox as part of UI rollback. + +**Done:** all seven findings are covered; no fake snapshot claims, hidden polling, cross-product status drift, or unintended historical writes were introduced. diff --git a/docs/plans/2026-11-12-scada-ui-consistency/MxAccessGateway.md b/docs/plans/2026-11-12-scada-ui-consistency/MxAccessGateway.md new file mode 100644 index 0000000..a71e1b8 --- /dev/null +++ b/docs/plans/2026-11-12-scada-ui-consistency/MxAccessGateway.md @@ -0,0 +1,419 @@ +# MxAccessGateway UI consistency Implementation Plan + +> **For Codex:** REQUIRED SUB-SKILL: Use `executeplan` to implement this plan task-by-task. + +**Goal:** Make browsing, dialogs and exception triage accessible while preserving shared Technical-Light chrome and runtime semantics. + +**Architecture:** Keep the .NET dashboard’s existing shared Theme shell and app-owned Galaxy/session state mapping. Adopt G1 assets, pilot native modal behavior locally, then converge repeated visual rules without touching COM worker or wire contracts. + +**Tech Stack:** net10.0 Blazor, Bootstrap CSS, Theme currently 0.5.0, xUnit 2.9.3, framework HtmlRenderer; real browser validation for DOM/focus. + +--- + +## 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. + +## Execution contract + +- Repository: `/Users/dohertj2/Desktop/MxAccessGateway`. All source/test paths below are relative to that root; use it as cwd unless a step states otherwise. +- Planning date: 2026-11-12. This chapter specifies future work; no implementation or test execution is claimed. +- Read the corresponding `/Users/dohertj2/Desktop/scadaproj/impeccable/MxAccessGateway.md`, the shared design-system report, the master plan and applicable `AGENTS.md` before execution. +- Reuse a suitable checkout; inspect `git status --short` and preserve user edits. No new worktree, commit, push, package publication or deployment is performed by authoring this plan. +- **Dependency gate:** complete shared Theme G1 compatibility audit, assign `THEME_VERSION`, and verify its artifact before consumer migration. `THEME_VERSION` is a placeholder, never a literal package version to publish. +- Shared G1 supplies semantic status ink (`--ok-ink:#236f34`, `--warn-ink:#855000`, `--bad-ink:#b42121`, `--idle-ink:#535d66`), `--ink-faint:#626970`, and independent blue `--info-ink`; product accent never recolors semantic informational notices. +- G1 adds `TechField.For`, `HintId`, `ErrorId`; callers supply input IDs, `aria-describedby` and `aria-invalid`. G1 adds `ThemeShell.AccentDeep`, `AccentTint`, `AccentBorder`, `AccentFocus` while preserving `Accent`. +- Shared accent aliases must resolve in shell scope: G1 uses `--accent-tint` directly or rebinds inherited aliases at `.app-shell`. Bootstrap `.btn-primary`/ghost component variables must follow shell accent for normal/hover/active/disabled states. Compare computed states before deleting any consumer override. +- G1 also supplies shared focus/busy/reduced-motion and filter/table/dialog recipes. `TechButton.BusyText` is optional; busy adds `aria-busy`. Caller-owned status/alert text announces outcomes, never secret values or every polling update. +- Pilot native dialogs in two consumers before extracting a common dialog component. Do not build a new component package during a first consumer migration. +- Restore/build first and record actual dependency/runtime failures. Complete GB bUnit/parser standardization first. Preserve xUnit, test SDK and Playwright versions unless a specific demonstrated compatibility fix is recorded in GB; do not perform later incidental framework upgrades. Never treat a skipped native/SQL/COM/live test as a pass. +- Each numbered step is one short action. When a step discovers broader product behavior, stop that task at its boundary and update this written plan before expanding implementation scope. + +## Verified starting point and package migration gate + +- `src/ZB.MOM.WW.MxGateway.Server/ZB.MOM.WW.MxGateway.Server.csproj:18` directly pins Theme 0.5.0; Secrets and Secrets.Ui are 0.6.2. Do not alter Secrets references until shared Secrets release `SECRETS_UI_VERSION` is assigned and its Theme graph agrees with `THEME_VERSION`. +- Current tests use xUnit and `Microsoft.AspNetCore.Components.Web.HtmlRenderer`; this repository does **not** currently use bUnit. Copy framework renderer setup from `Dashboard/SettingsPageTagVisibilityRenderTests.cs`; do not paste bUnit APIs here. +- Current snapshot pages use one in-process shared feed (`Dashboard/Components/DashboardPageBase.cs`), not one SignalR loopback per page. Preserve subscription cancellation and ACL behavior. +- Record baseline using `dotnet restore src/ZB.MOM.WW.MxGateway.Server/ZB.MOM.WW.MxGateway.Server.csproj`, `dotnet list src/ZB.MOM.WW.MxGateway.Server/ZB.MOM.WW.MxGateway.Server.csproj package --include-transitive`, and focused dashboard tests. After G1, edit the explicit Theme pin, restore and confirm the resolved graph; compare output before any local CSS deletion. +- Blue accent remains `#2f5fd0`. No worker executable, alarms protocol, role policy, or gateway option changes belong to this migration. + +## Findings coverage + +| Report finding | Planned task | Primary proof | +| --- | --- | --- | +| MX-01 keyboard/touch subscriptions | MX-01 | Named toggle render + keyboard watch browser flow | +| MX-02 unmanaged overlays | MX-02 | Native dialog render + actual focus/inertness checks | +| MX-03 unnamed browse search | MX-03 | Accessible field + clear/no-match behavior | +| MX-04 equal-weight overview metrics | MX-04 | Fault-first fixture, all counters retained | +| MX-05 copied colors/component rules | MX-05 | Computed token/contrast + before/after views | +| MX-06 hover-only error detail | MX-06 | Safe diagnostic disclosure and retry | +| MX-07 tiny tree controls | MX-07 | Coarse-pointer hit areas and containment | +| MX-08 destination/action vocabulary | MX-08 | Rail/title/heading consistency | + +### Shared test helper used below + +Create `src/ZB.MOM.WW.MxGateway.Tests/Dashboard/DashboardMarkup.cs` once. Use this complete helper for markup-only contracts; it does not simulate clicks, keyboard focus or JS interop: + +```csharp +using Microsoft.AspNetCore.Components; +using Microsoft.AspNetCore.Components.Web; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Logging; +namespace ZB.MOM.WW.MxGateway.Tests.Dashboard; +internal static class DashboardMarkup +{ + internal static async Task RenderAsync(Dictionary values) + where T : IComponent + { + var services = new ServiceCollection(); + services.AddLogging(); + await using var provider = services.BuildServiceProvider(); + await using var renderer = new HtmlRenderer(provider, + provider.GetRequiredService()); + return await renderer.Dispatcher.InvokeAsync(async () => + { + var result = await renderer.RenderComponentAsync( + ParameterView.FromDictionary(values)); + return result.ToHtmlString(); + }); + } +} +``` + +JS-dependent lifecycle work belongs in `OnAfterRenderAsync`, which static rendering does not execute. For page tests requiring DI, extend the existing SettingsPage fixture pattern with real service interfaces and inert snapshot feed; do not register null services solely to make rendering pass. + +## MX-01: Make tree expansion and watching explicit + +**Files:** + +- Modify `src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Shared/BrowseTreeNodeView.razor` +- Modify `src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/BrowsePage.razor` +- Create `src/ZB.MOM.WW.MxGateway.Tests/Dashboard/BrowseTreeAccessibilityTests.cs` +- Create `src/ZB.MOM.WW.MxGateway.Tests/Dashboard/DashboardMarkup.cs` + +**Step 1 — Establish the failing behavior.** Add this test to the new xUnit class with imports for the existing shared component, dashboard model and `ZB.MOM.WW.GalaxyRepository.Grpc`. + +```csharp +[Fact] +public async Task Node_toggle_names_its_object_and_exposes_collapsed_state() +{ + var node = new DashboardBrowseNode { + Object = new GalaxyObject { BrowseName = "Pump01" }, HasChildrenHint = true + }; + var markup = await DashboardMarkup.RenderAsync( + new() { ["Node"] = node }); + Assert.Contains("Expand Pump01", markup); + Assert.Contains("aria-expanded=" + '"' + "false" + '"', markup); +} +``` + +**Step 2 — Run the focused check.** From the repository root: + +```bash +dotnet test src/ZB.MOM.WW.MxGateway.Tests/ZB.MOM.WW.MxGateway.Tests.csproj --filter FullyQualifiedName~BrowseTreeAccessibilityTests +``` + +Expected before: the collapsed node exposes generic Toggle and lacks `aria-expanded`; the named/state assertions fail. + +**Step 3 — Implement in small edits.** + +1. Keep `OnLoadChildren` and `OnAddTag` callbacks and lazy rendering unchanged. +2. Replace label-span click handling with a named expansion button; add stable controls ID and lowercase `aria-expanded`. +3. Expose a real Watch attribute button on each expanded attribute and search hit; call the existing `AddTagAsync` path exactly once. Keep right-click/double-click only as accelerators. +4. Add a browser acceptance record `docs/ui-validation/technical-light-browse.md` including permitted read-only fixture account/scope and full keyboard sequence. + +**Step 4 — Verify the change.** Re-run Step 2; expected after: PASS for the named tests or all stated visual checks. In a disposable fixture expand with Enter, Tab to Watch, activate with Space, and assert exactly one subscription row. Repeat on a touch viewport and verify repeated watch does not duplicate subscriptions. Changing/removing tags still obeys existing ACL and cleanup behavior. + +**Step 5 — Commit.** Stage only the listed production/test/evidence files, inspect `git diff --cached`, then `git commit -m "fix: make Galaxy watch workflow keyboard accessible"`. Do not include generated credentials, runtime data or unrelated edits. + +## MX-02: Pilot native dialogs with actual focus management + +**Files:** + +- Modify `src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Shared/ConfirmDialog.razor` +- Modify `src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/ApiKeysPage.razor` +- Create `src/ZB.MOM.WW.MxGateway.Server/wwwroot/js/dashboard-dialog.js` +- Create `src/ZB.MOM.WW.MxGateway.Tests/Dashboard/ConfirmDialogRenderTests.cs` + +**Step 1 — Establish the failing behavior.** Render a requested confirmation. The test below proves that a semantic native modal is emitted; the browser procedure below is the focus/inertness gate, not this markup assertion. + +```csharp +[Fact] +public async Task Requested_confirmation_renders_named_native_dialog() +{ + var markup = await DashboardMarkup.RenderAsync(new() { + ["IsOpen"] = true, ["Title"] = "Close session example", ["Message"] = "Clients will disconnect." + }); + Assert.Contains("` element; the title and cancel text currently render in a presentation overlay. + +**Step 3 — Implement in small edits.** + +1. Replace the div/backdrop mechanism with ``; call `showModal()` only after interactive render. +2. Import the local JS module once, capture the invoking element before showModal, and restore focus after close if the trigger still exists. +3. Use a real `cancel` event listener with its `event` parameter; prevent dismissal while busy and otherwise invoke the safe cancel callback. Do not read `window.event` or use an event after awaiting a Blazor round trip. +4. Apply the same local pilot behavior to create-key overlay. Remove duplicate backdrop once native modal is used; keep all policy gates and pending-state ownership. +5. Dispose listeners/module and handle circuit disconnect; do not trap Tab manually over native dialog or dispatch a write from JS. + +**Step 4 — Verify the change.** Re-run Step 2; expected after: PASS for the named tests or all stated visual checks. Use a real browser: focus trigger → open → Tab/Shift+Tab cycles in dialog; outside controls cannot receive focus; Escape cancels only when safe; focus returns. During a delayed confirm, Escape cannot issue a second operation. Verify validation feedback and one-time-token handling without capturing plaintext tokens. Record this as consumer pilot 1; extraction waits for OEE pilot 2. + +**Step 5 — Commit.** Stage only the listed production/test/evidence files, inspect `git diff --cached`, then `git commit -m "fix: manage gateway dialog focus and dismissal"`. Do not include generated credentials, runtime data or unrelated edits. + +### MX-02 real-browser focus check + +Run in the connected browser automation session against a disposable local fixture; `page` is that session’s Playwright page. First navigate to a session whose safe confirmation trigger is named below; match the actual fixture’s accessible name rather than guessing a production account. + +```javascript +const trigger = page.getByRole('button', {name: 'Close session', exact: true}); +await trigger.focus(); +await trigger.press('Enter'); +const dialog = page.getByRole('dialog'); +await dialog.waitFor({state: 'visible'}); +if (!(await dialog.evaluate(d => d.contains(document.activeElement)))) + throw new Error('Initial focus outside confirmation'); +for (let i = 0; i < 24; i++) { + await page.keyboard.press(i % 2 ? 'Shift+Tab' : 'Tab'); + if (!(await dialog.evaluate(d => d.contains(document.activeElement)))) + throw new Error('Focus escaped confirmation'); +} +await page.keyboard.press('Escape'); +await dialog.waitFor({state: 'hidden'}); +if (!(await trigger.evaluate(e => e === document.activeElement))) + throw new Error('Trigger focus not restored'); +``` + +This opens then cancels; it sends no close-session request. Repeat on create-key dialog without submitting, then use an isolated delayed fake to prove busy confirm dispatches exactly once. Never run an acceptance write against a live session merely to verify focus. + +## MX-03: Label and recover browse search + +**Files:** + +- Modify `src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/BrowsePage.razor` +- Modify `src/ZB.MOM.WW.MxGateway.Tests/Dashboard/DashboardBrowseServiceTests.cs` +- Create `src/ZB.MOM.WW.MxGateway.Tests/Dashboard/BrowseSearchAccessibilityTests.cs` + +**Step 1 — Establish the failing behavior.** Use the existing BrowseService fake/model setup to render BrowsePage with at least one cached root. Add a field contract test asserting label `for="browse-search"`, input `id="browse-search"` and non-empty results/no-match text. Keep query/cap tests in DashboardBrowseServiceTests. + +**Step 2 — Run the focused check.** From the repository root: + +```bash +dotnet test src/ZB.MOM.WW.MxGateway.Tests/ZB.MOM.WW.MxGateway.Tests.csproj --filter FullyQualifiedName~BrowseSearchAccessibilityTests +``` + +Expected before: search has only a placeholder and no permanent label/clear action. + +**Step 3 — Implement in small edits.** + +1. Add persistent “Filter Galaxy attributes” label plus hint/result IDs. +2. Set caller-owned `aria-describedby` on input; use the G1 field association recipe if TechField is adopted. +3. Add Clear search that cancels any obsolete pending query, resets matches and returns focus; display no matches distinctly from no cache. +4. Publish a polite count only when the search result changes, not on every live value refresh. + +**Step 4 — Verify the change.** Re-run Step 2; expected after: PASS for the named tests or all stated visual checks. Type a non-match, clear via keyboard, and verify prior tree expansion/subscriptions remain. Rapidly type two different queries; late results must not overwrite the current query. Use existing server cap and indexes, no new full-tree scan. + +**Step 5 — Commit.** Stage only the listed production/test/evidence files, inspect `git diff --cached`, then `git commit -m "fix: label Galaxy search and clarify no-match recovery"`. Do not include generated credentials, runtime data or unrelated edits. + +## MX-04: Make overview prioritize faults while preserving counters + +**Files:** + +- Modify `src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/DashboardHome.razor` +- Modify `src/ZB.MOM.WW.MxGateway.Server/wwwroot/css/site.css` +- Create `src/ZB.MOM.WW.MxGateway.Tests/Dashboard/DashboardHomeRenderTests.cs` + +**Step 1 — Establish the failing behavior.** Build a snapshot fixture using the existing SettingsPage stub/feed idiom, with one fault, one session and non-zero supporting counters. Assert the fault message and affected-session link render, then assert supporting counters are still reachable in a labeled details element. + +**Step 2 — Run the focused check.** From the repository root: + +```bash +dotnet test src/ZB.MOM.WW.MxGateway.Tests/ZB.MOM.WW.MxGateway.Tests.csproj --filter FullyQualifiedName~DashboardHomeRenderTests +``` + +Expected before: fault context is not linked from an exception-first summary and supporting counters are not a disclosure. + +**Step 3 — Implement in small edits.** + +1. Render sampled-time/gateway-state context beside the heading. +2. Lead the content with actionable recent faults and links to the existing sessions route; preserve server-side visibility filtering. +3. Keep sessions/workers/queue context grouped; move lifetime/event/repository-size counters to a labeled supporting-counters disclosure. +4. Separate Repository status link (`/galaxy`) from Browse attributes (`/browse`); do not add invented metrics or new polling. + +**Step 4 — Verify the change.** Re-run Step 2; expected after: PASS for the named tests or all stated visual checks. Review a healthy snapshot, mixed fault snapshot and zero-session snapshot side by side at desktop/mobile. Capture the retained counter inventory and confirm the first viewport identifies the fault. Numeric values must match the same snapshot before/after composition. + +**Step 5 — Commit.** Stage only the listed production/test/evidence files, inspect `git diff --cached`, then `git commit -m "refactor: prioritize gateway fault context on overview"`. Do not include generated credentials, runtime data or unrelated edits. + +## MX-05: Adopt shared ink and remove duplicated visual rules + +**Files:** + +- Modify `src/ZB.MOM.WW.MxGateway.Server/ZB.MOM.WW.MxGateway.Server.csproj` +- Modify `src/ZB.MOM.WW.MxGateway.Server/wwwroot/css/site.css` +- Modify `src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Layout/MainLayout.razor` +- Create `docs/ui-validation/technical-light-token-migration.md` + +**Step 1 — Establish the failing behavior.** This is a CSS/package migration: capture the same fixture screens and computed colors before editing. Do not write a test that merely asserts a CSS declaration exists. + +**Step 2 — Run the focused check.** From the repository root: + +```bash +dotnet build src/ZB.MOM.WW.MxGateway.Server/ZB.MOM.WW.MxGateway.Server.csproj +dotnet test src/ZB.MOM.WW.MxGateway.Tests/ZB.MOM.WW.MxGateway.Tests.csproj --filter FullyQualifiedName~Dashboard +``` + +Expected before: the baseline contrast check identifies inherited failing status ink and local hardcoded shade islands; builds/tests should already pass. + +**Step 3 — Implement in small edits.** + +1. Wait for `THEME_VERSION`; update Theme pin and resolve the graph including Secrets.Ui. +2. Map local success/failure notices to semantic ink tokens, not bright status swatches. Info uses independent blue `--info-ink`. +3. Replace repeated zebra/hover/active/tint literals with shared tokens; delete only byte/behavior-equivalent button/field rules after computed-style comparison. Keep browse geometry and domain classes local. +4. Retain blue shell accent; if providing the new optional accent family, use G1-approved matching values, not green/blue mixtures. + +**Step 4 — Verify the change.** Re-run Step 2; expected after: PASS for the named tests or all stated visual checks. Run the master computed contrast matrix on local alert/tree/table states; compare hover, focus, disabled, busy and validation states. No extra unit tests for this reversible styling change. Record package graph and screenshots. + +**Step 5 — Commit.** Stage only the listed production/test/evidence files, inspect `git diff --cached`, then `git commit -m "style: adopt shared gateway status ink and tokens"`. Do not include generated credentials, runtime data or unrelated edits. + +## MX-06: Expose safe errors and retry without losing context + +**Files:** + +- Modify `src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Shared/BrowseTreeNodeView.razor` +- Modify `src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/BrowsePage.razor` +- Update `docs/ui-validation/technical-light-browse.md` + +**Step 1 — Establish the failing behavior.** Use an isolated browser fixture whose Pump01 child load fails once with long safe diagnostic text, then succeeds on retry. Record the failing browser flow below. Do not claim static HtmlRenderer can expand the private node state or dispatch callbacks; the existing named-toggle render tests remain regression checks. + +**Step 2 — Run the focused check.** From the repository root: + +```bash +dotnet test src/ZB.MOM.WW.MxGateway.Tests/ZB.MOM.WW.MxGateway.Tests.csproj --filter FullyQualifiedName~BrowseTreeAccessibilityTests +``` + +Expected before: the failure text is abbreviated and the existing loaded/error path lacks a dedicated retry control. + +**Step 3 — Implement in small edits.** + +1. Render safe short failure summary plus named Retry load; allow retry when LoadState is Error while preserving siblings. +2. Expose full safe detail under a native disclosure; continue using the existing redaction boundary and never print secrets/connection strings. +3. Use one alert for user-triggered failures and polite recovery status; do not announce every poll. +4. Retain watched tags and current search/tree context while retry runs. + +**Step 4 — Verify the change.** Re-run Step 2; expected after: PASS for the named tests or all stated visual checks. Induce child-load failure and recovery; use keyboard and touch to read detail/retry. Verify success does not rebuild the entire tree or clear subscription rows. Confirm repeated failed retries are bounded by existing request behavior, not an added automatic retry loop. + +**Step 5 — Commit.** Stage only the listed production/test/evidence files, inspect `git diff --cached`, then `git commit -m "fix: expose recoverable Galaxy browse errors"`. Do not include generated credentials, runtime data or unrelated edits. + +### MX-06 failing recovery browser flow + +Run against the isolated once-failing Pump01 browse fixture in the connected Playwright session. The fixture must hold one previously watched sibling tag and log load-attempt counts so retry/recovery can be verified without production dependencies. + +```javascript +await page.getByRole('button', {name: 'Expand Pump01', exact: true}).press('Enter'); +const retry = page.getByRole('button', {name: 'Retry loading Pump01', exact: true}); +await retry.waitFor({state: 'visible'}); // fails before a retry action exists +await page.getByText('Show diagnostic details for Pump01', {exact: true}).press('Space'); +if (!(await page.getByText('Fixture child load failed', {exact: true}).isVisible())) + throw new Error('Diagnostic detail is unavailable without hover'); +await retry.press('Enter'); +await page.getByRole('button', {name: 'Watch Pump01.PV', exact: true}) + .waitFor({state: 'visible'}); +``` + +The exact names above are the planned accessible contract for this fixture. Assert the sibling subscription count is unchanged and fixture load count increased by exactly one after Retry. Static source/render checks are supplementary; successful recovery requires this actual DOM/callback sequence. + +## MX-07: Apply shared coarse-pointer and containment rules + +**Files:** + +- Modify `src/ZB.MOM.WW.MxGateway.Server/wwwroot/css/site.css` +- Modify `src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Shared/BrowseTreeNodeView.razor` +- Modify `src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/BrowsePage.razor` +- Update `docs/ui-validation/technical-light-browse.md` + +**Step 1 — Establish the failing behavior.** Capture tree toggle and subscription remove control bounding boxes at compact desktop and coarse-pointer mobile. Use the same seeded 200-character tag path; no declaration-mirroring unit test. + +**Step 2 — Run the focused check.** From the repository root: + +```bash +dotnet build src/ZB.MOM.WW.MxGateway.Server/ZB.MOM.WW.MxGateway.Server.csproj +``` + +Expected before: the 1.1rem toggle is below the proposed coarse-pointer 44px target; long-path mobile behavior must be measured. + +**Step 3 — Implement in small edits.** + +1. Adopt G1 sizing utilities, keeping visible chevrons compact but hit areas ≥44px on coarse pointers. +2. Ensure grid children use min-width:0 and long tables/tree scroll inside named regions rather than widening the document. +3. Keep remove/watch actions visible or accessible in row detail with full labels; preserve full tag value for copying. + +**Step 4 — Verify the change.** Re-run Step 2; expected after: PASS for the named tests or all stated visual checks. In browser verify 390px and 200% zoom, Tab into table scroller and reach last columns; inspect `document.documentElement.scrollWidth <= innerWidth`. Check desktop row density remains usable. + +**Step 5 — Commit.** Stage only the listed production/test/evidence files, inspect `git diff --cached`, then `git commit -m "style: improve gateway browse touch targets and containment"`. Do not include generated credentials, runtime data or unrelated edits. + +## MX-08: Normalize destination and action language + +**Files:** + +- Modify `src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Layout/MainLayout.razor` +- Modify `src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/DashboardHome.razor` +- Modify `src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/Login.razor` +- Update `docs/ui-validation/technical-light-token-migration.md` + +**Step 1 — Establish the failing behavior.** Compare visible rail, h1 and document title in the existing fixture. This copy-only change needs a review checklist rather than a brittle exact-markup unit test. + +**Step 2 — Run the focused check.** From the repository root: + +```bash +dotnet build src/ZB.MOM.WW.MxGateway.Server/ZB.MOM.WW.MxGateway.Server.csproj +``` + +Expected before: the rail says Dashboard while the landing heading says Overview; capitalization differs across sisters. + +**Step 3 — Implement in small edits.** + +1. Use Overview consistently for the landing destination; use API keys / Sign out / Refresh in family sentence case. +2. Keep route URLs, stable NavRailSection keys and runtime status enum text unchanged. +3. Review fault and action wording with real session identifiers; do not rename domain contracts or policy constants. + +**Step 4 — Verify the change.** Re-run Step 2; expected after: PASS for the named tests or all stated visual checks. Confirm one active rail item per route, correct document title and current heading. Run existing logout/auth/policy tests and source review for unchanged keys. + +**Step 5 — Commit.** Stage only the listed production/test/evidence files, inspect `git diff --cached`, then `git commit -m "docs: align gateway UI labels with shared vocabulary"`. Do not include generated credentials, runtime data or unrelated edits. + +## Cross-cutting state and viewport matrix + +| State | Expected contract | Verification | +| --- | --- | --- | +| First load / slow work | Page identity remains; busy action disabled with meaningful busy text; no false successful zero | Delayed fixture and keyboard | +| Healthy | Text label plus status token, sampled time, real scope | Representative fixture | +| Warning / failed dependency | Plain summary, affected scope and recovery; safe detail disclosure | Fault fixture; no raw secret/connection string | +| Refresh fails after success | Keep last good data visibly marked stale; retry does not clear context | Sequential success/failure fake | +| Empty / no matches | Different from loading/failure; clear-filter or next action | Empty source and filtered-to-zero separately | +| Unavailable / unknown | Show unknown/n/a, never substitute numeric zero or Healthy | Null/missing fixture | +| Permission denied | Route and action gates remain server-enforced; nav reflects existing policy | Viewer/Admin/denied accounts | +| Long content | Full identifiers available in detail/copy context; table scroll local | 200-character path and error | +| Keyboard / modal | Visible focus; enter/space activation; real modal inertness and focus restoration | Browser test, not HtmlRenderer | +| Narrow / zoom / motion | 1440×900, 1024×768, 390×844, 200% zoom; reduced motion keeps status feedback | Batched visual pass and at most one confirmation pass | + +No runtime timestamps or status values in a mockup are deployment evidence. Keep status domain mapping app-owned. Test color contrast against actual computed backgrounds; screenshots alone do not establish WCAG compliance. + +## Release, rollback and evidence + +1. Run `dotnet test src/ZB.MOM.WW.MxGateway.Tests/ZB.MOM.WW.MxGateway.Tests.csproj --filter FullyQualifiedName~Dashboard`; then one full project test run if no new failures remain. Record COM/Windows/infrastructure requirements and actual skipped cases; do not disable them to manufacture green results. +2. Build the Server with the resolved shared package, capture asset/font HTTP 200s in the disposable local browser host and verify browser console has no dialog import or Blazor errors. +3. Record an evidence bundle containing dependency graph, commit IDs, viewport captures, measured contrast, keyboard/focus outcomes and state matrix. No actual secrets, token screenshots or operational credentials. +4. Follow the repository's existing release process separately. This plan authorizes no deployment and no restart of a live gateway or COM worker. A live gate must use an isolated fixture before an operator-approved environment rollout. +5. Roll back by reverting the consumer migration commits and restoring the former explicit Theme pin (currently 0.5.0) plus matching dependency graph. Do not mutate published packages. This UI work has no database migration; if a task introduces one, stop and rescope. +6. Removing the native dialog enhancement must restore its previous component version coherently; do not roll back just the JS module while leaving calling markup. Validate browse/watch and session confirmation after rollback. + +**Done:** every finding above is mapped, tests and actual browser outcomes are recorded, shared look/feel agrees with G1, and runtime/permission boundaries are preserved. diff --git a/docs/plans/2026-11-12-scada-ui-consistency/OtOpcUa.md b/docs/plans/2026-11-12-scada-ui-consistency/OtOpcUa.md new file mode 100644 index 0000000..d5bd420 --- /dev/null +++ b/docs/plans/2026-11-12-scada-ui-consistency/OtOpcUa.md @@ -0,0 +1,376 @@ +# 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>(p => p + .Add(x => x.Value, new EditContext(new object())) + .AddChildContent()); + 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(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(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(); + 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 = "" + new string('x', 2000); + var cut = Render(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(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>> 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>(new IOException("synthetic outage")) + : Task.FromResult>(Array.Empty()) }; + Services.AddSingleton(svc); + var cut = Render(); + 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(); + Services.AddSingleton>(feed); + var cut = Render(); + 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 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. diff --git a/docs/plans/2026-11-12-scada-ui-consistency/Overview.md b/docs/plans/2026-11-12-scada-ui-consistency/Overview.md new file mode 100644 index 0000000..bb85d70 --- /dev/null +++ b/docs/plans/2026-11-12-scada-ui-consistency/Overview.md @@ -0,0 +1,209 @@ +# 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 + { + ["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 a screen reader's row reading order. +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, 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. diff --git a/docs/plans/2026-11-12-scada-ui-consistency/ScadaBridge.md b/docs/plans/2026-11-12-scada-ui-consistency/ScadaBridge.md new file mode 100644 index 0000000..40188b1 --- /dev/null +++ b/docs/plans/2026-11-12-scada-ui-consistency/ScadaBridge.md @@ -0,0 +1,272 @@ +# 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`), 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. diff --git a/docs/plans/2026-11-12-scada-ui-consistency/Secrets.md b/docs/plans/2026-11-12-scada-ui-consistency/Secrets.md new file mode 100644 index 0000000..a417838 --- /dev/null +++ b/docs/plans/2026-11-12-scada-ui-consistency/Secrets.md @@ -0,0 +1,238 @@ +# Shared Secrets UI Consistency Implementation Plan + +> **For Codex:** REQUIRED SUB-SKILL: Use `executeplan` to implement this plan task-by-task. + +**Goal:** Isolate secret-editor targets, make privileged administration accessible and recoverable, and ship one consistent UI to every sister host. + +**Architecture:** Fix target/draft identity before visual changes, then adopt the reviewed Theme API and shared interaction recipes in the existing Razor library. Preserve metadata-only lists, separate manage/reveal authorization, fail-closed reveal auditing, committed mutation semantics, tombstones and cache invalidation. Domain services remain unchanged; generic modal behavior is only considered for extraction after two real consumer pilots. + +**Tech Stack:** .NET 10 Razor Class Library, ZB.MOM.WW.Theme, existing ISecretStore/ISecretCipher/IAuditWriter, xUnit 2.9.3, bUnit 2.7.2 after GB (`BunitContext` / `Render`), native DOM dialog/focus APIs when required. + +--- + +## 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 + +- Cwd for all commands: `/Users/dohertj2/Desktop/scadaproj/ZB.MOM.WW.Secrets`; all task files below are relative to that cwd. +- Inputs: `/Users/dohertj2/Desktop/scadaproj/impeccable/Secrets.md`, shared recommendations, master plan and Theme G1 gate. Review source unchanged between review baseline and current umbrella HEAD `d93ca7b`; record actual execution HEAD. +- Current library source version: `Directory.Build.props` → `0.6.6`; Theme central pin `Directory.Packages.props` → `0.2.0`. Consumers may resolve higher Theme versions; use restored graphs as truth. +- `THEME_VERSION`: actual compatible release after G1. `SECRETS_UI_VERSION`: actual package release selected for these changes after its own compatibility review. Neither string is a version to commit literally. Do not assume `0.6.0` or republish an existing immutable package. +- SEC-01 target isolation may proceed after GB closes while Theme G1 is pending. All visual/API adoption tasks depend on G1. Host adoption depends on both chosen packages. +- G1 API: additive `TechField.For`, `HintId`, `ErrorId`; callers provide matching control `id`, `aria-describedby`, `aria-invalid`. BusyText/aria-busy are shared; caller live outcome regions must never contain plaintext. Theme status text uses dedicated ink tokens; information-state blue is independent of product accent. +- Complete the required bUnit 2.7.2 migration in GB first. Subsequent tasks preserve that validated test stack; backend/storage redesign, real-secret fixtures and real reveals are outside these UI tasks. + +Run baseline from the stated cwd: + +```sh +dotnet test tests/ZB.MOM.WW.Secrets.Ui.Tests/ZB.MOM.WW.Secrets.Ui.Tests.csproj +``` + +Expected PASS; record restore warnings/count. Feed/SDK or existing parser/test-stack failures are baseline blockers, to record in GB; the prescribed 2.7.2 migration and compatibility verification must close before these tasks. New tests below extend the named existing classes and retain their existing usings/helpers. Test data is synthetic. + +## SEC-01 · Isolate Add/Rotate targets and pending editor lifetimes + +**Covers:** review SEC-06; highest priority before aesthetic work. **Depends:** baseline only. + +**Modify:** `src/ZB.MOM.WW.Secrets.Ui/Components/SecretEditor.razor`; `src/ZB.MOM.WW.Secrets.Ui/Components/SecretsList.razor`; `tests/ZB.MOM.WW.Secrets.Ui.Tests/SecretEditorTests.cs`; `tests/ZB.MOM.WW.Secrets.Ui.Tests/SecretsListTests.cs`; `tests/ZB.MOM.WW.Secrets.Ui.Tests/Fakes/RecordingSecretStore.cs` for optional delayed-call hooks. + +1. Add this test inside `SecretEditorTests`, reusing `RegisterServices()`: + +```csharp +[Fact] +public void ChangingRotateTarget_DoesNotReuseAnotherSecretsDraft() +{ + var (store, _, cipher) = RegisterServices(); + var a = new SecretName("app/a"); + var b = new SecretName("app/b"); + store.Seed(cipher.Encrypt(a, "old-a", SecretContentType.Text) with { Description = "A" }); + store.Seed(cipher.Encrypt(b, "old-b", SecretContentType.Json) with { Description = "B" }); + var auth = this.AddAuthorization(); + auth.SetAuthorized("reviewer"); + auth.SetPolicies(SecretsAuthorization.ManagePolicy); + var cut = Render(p => p.Add(x => x.ExistingName, a)); + cut.Find("[data-testid=secret-value]").Change("draft-for-a"); + cut.Render(p => p.Add(x => x.ExistingName, b)); + cut.WaitForAssertion(() => + { + Assert.Equal("B", cut.Find("[data-testid=secret-description]").GetAttribute("value")); + Assert.Equal("", cut.Find("[data-testid=secret-value]").GetAttribute("value") ?? ""); + }); +} +``` + +2. Run `dotnet test tests/ZB.MOM.WW.Secrets.Ui.Tests/ZB.MOM.WW.Secrets.Ui.Tests.csproj --filter FullyQualifiedName~ChangingRotateTarget_DoesNotReuseAnotherSecretsDraft`; expected FAIL because `_metadataLoaded` and `_value` survive target changes. +3. Track editor identity explicitly (Add vs Rotate + exact secret name). On identity change, increment a generation, cancel the previous metadata read and reset name/description/type/value/error/restore-confirmation/loading flags before loading the new metadata. Apply read results only if generation and identity still match. Capture immutable target identity when submitting. Preserve failed-save drafts only for that identity. The list also keys editor instances by mode/name and tracks its editor generation so a superseded completion cannot close a newer editor. Disable Add/Rotate/Cancel target switching while a committed mutation outcome is pending; explain pending state instead of claiming cancellation rolled back a write. +4. Add tests for Rotate→Add; same-target rerender preserving unsaved text; delayed A metadata completing after B; parent row A→B switching; cancellation during pending write; and stale `OnSaved` not closing a new editor. Add optional `GetOverride`/`UpsertOverride` delegates to the recording fake for TaskCompletionSource-controlled delay rather than sleeping. Run `dotnet test tests/ZB.MOM.WW.Secrets.Ui.Tests/ZB.MOM.WW.Secrets.Ui.Tests.csproj --filter "FullyQualifiedName~SecretEditor|FullyQualifiedName~SecretsList|FullyQualifiedName~AuditFailureAfterCommit"`; expected PASS and existing audit/cache semantics unchanged. +5. Stage only the five named files; commit `fix(secrets-ui): isolate drafts and pending operations by editor target`. + +## SEC-02 · Adopt the shared Theme field and state API + +**Covers:** SEC-01; DS-01/02/04/06. **Depends:** SEC-01 + G1. + +**Modify:** `Directory.Packages.props`; `src/ZB.MOM.WW.Secrets.Ui/Components/SecretEditor.razor`; `tests/ZB.MOM.WW.Secrets.Ui.Tests/SecretEditorTests.cs`. + +1. Add a rendered association regression in `SecretEditorTests`: + +```csharp +[Fact] +public void EveryEditorControl_HasAnAssociatedLabel() +{ + RegisterServices(); + var cut = Render(); + foreach (var control in cut.FindAll("input:not([type=hidden]),select")) + { + var id = control.Id; + Assert.False(string.IsNullOrWhiteSpace(id)); + Assert.NotNull(cut.Find($"label[for='{id}']")); + } +} +``` + +2. Run `dotnet test tests/ZB.MOM.WW.Secrets.Ui.Tests/ZB.MOM.WW.Secrets.Ui.Tests.csproj --filter FullyQualifiedName~EveryEditorControl_HasAnAssociatedLabel`; expected FAIL on absent IDs/associations. +3. Set the actual Theme pin to `THEME_VERSION`. Give each editor instance stable unique control/hint/error IDs, pass `For`, `HintId`, `ErrorId`, and wire child attributes. Include required/name-format hints and field-local errors. New secret value stays a password input with `autocomplete="new-password"`; never prefill stored plaintext. Use BusyText and aria-busy; error/status text uses new semantic ink classes, not signal colors. +4. Add two-instance unique-ID and invalid-name `aria-invalid`/description tests; run the `SecretEditorTests` filter then the whole UI suite. Expected PASS. Browser-verify label activation, correct names and field errors with keyboard/screen reader; never announce new values. Use computed contrast and visual inspection for palette changes, not CSS-string tests. +5. Stage the three named files; commit `fix(secrets-ui): adopt shared field associations and readable states`. + +## SEC-03 · Make deletion keyboard accessible inside real hosts + +**Covers:** SEC-02; DS-04/05. **Depends:** G1 dialog recipe + SEC-01. + +**Modify:** `src/ZB.MOM.WW.Secrets.Ui/Components/ConfirmDeleteModal.razor`; `src/ZB.MOM.WW.Secrets.Ui/Components/SecretsList.razor`; `tests/ZB.MOM.WW.Secrets.Ui.Tests/ConfirmDeleteModalTests.cs`. +**Create if recipe requires DOM enhancement:** `src/ZB.MOM.WW.Secrets.Ui/wwwroot/js/secrets-dialog.js`. + +1. Add a regression inside `ConfirmDeleteModalTests` (same registration/auth setup as existing first test): + +```csharp +[Fact] +public void DeleteDialog_HasANameLinkedToTheExactTarget() +{ + Services.AddSingleton(new RecordingSecretStore()); + Services.AddSingleton(new CapturingAuditWriter()); + var cut = Render(p => p + .Add(x => x.Visible, true).Add(x => x.Name, new SecretName("app/a"))); + var dialog = cut.Find("[role=dialog]"); + var titleId = dialog.GetAttribute("aria-labelledby"); + Assert.False(string.IsNullOrWhiteSpace(titleId)); + Assert.Contains("app/a", cut.Find($"[id='{titleId}']").TextContent); + Assert.Equal("true", dialog.GetAttribute("aria-modal")); +} +``` + +2. Run `dotnet test tests/ZB.MOM.WW.Secrets.Ui.Tests/ZB.MOM.WW.Secrets.Ui.Tests.csproj --filter FullyQualifiedName~DeleteDialog_HasANameLinkedToTheExactTarget`; expected FAIL on missing association. If DOM module initialization is introduced, add an exact bUnit module stub in test setup before rerunning; do not weaken the existing strict assertion to allow arbitrary browser `confirm`/`alert`. +3. Apply the shared confirmation recipe: unique heading/description association, initial Cancel focus, contained tab order, inert background, safe Escape, focus return to originating row. Retain `.zb-secrets-*` namespace to avoid the documented Bootstrap `.modal{display:none}` collision. Retain awaited busy operation and exact target; after deletion choose next logical row/heading if trigger vanished. DOM handler receives its actual event argument; never use `window.event`. Dispose event listeners and restore any prior inert state. +4. Add cancel-does-not-delete, busy double activation, failed delete retains target and error, and next-focus-target selection tests in the named files. Run the `ConfirmDeleteModalTests` filter and whole UI suite; expected PASS. Browser-test actual focus/Escape/background isolation in two hosts including one Bootstrap host: bUnit markup cannot establish focus containment. +5. Stage only named modified files plus the module if created; commit `fix(secrets-ui): apply accessible confirmation lifecycle`. + +## SEC-04 · Separate list loading, commit and refresh outcomes + +**Covers:** SEC-03; DS-04/05. **Depends:** SEC-01. + +**Modify:** `src/ZB.MOM.WW.Secrets.Ui/Components/SecretsList.razor`; `tests/ZB.MOM.WW.Secrets.Ui.Tests/SecretsListTests.cs`; `tests/ZB.MOM.WW.Secrets.Ui.Tests/Fakes/RecordingSecretStore.cs`. + +1. Extend the recording fake with optional `ListFault` and `ListCalls`; preserve normal behavior when unset. Add a list regression inside `SecretsListTests`: + +```csharp +[Fact] +public void InitialListFailure_IsRetryableAndIsNotAnEmptyInventory() +{ + var store = new RecordingSecretStore { ListFault = new IOException("synthetic outage") }; + Services.AddSingleton(store); + Services.AddSingleton(new FakeCipher()); + Services.AddSingleton(new CapturingAuditWriter()); + var cut = Render(); + cut.WaitForAssertion(() => Assert.NotNull(cut.Find("[data-testid=list-error]"))); + Assert.DoesNotContain("No secrets.", cut.Markup); + store.ListFault = null; + cut.Find("[data-testid=list-retry]").Click(); + cut.WaitForAssertion(() => Assert.Contains("No secrets.", cut.Markup)); +} +``` + +2. Run `dotnet test tests/ZB.MOM.WW.Secrets.Ui.Tests/ZB.MOM.WW.Secrets.Ui.Tests.csproj --filter FullyQualifiedName~InitialListFailure_IsRetryableAndIsNotAnEmptyInventory`; expected FAIL from unhandled initial list exception (after fake compiles). +3. Catch list failures locally, preserve previous metadata if present, and show Retry with a polite status region. Keep initial loading distinct from empty. Track mutation committed separately from list refresh; show “Change saved; list refresh failed” if necessary. Retry refresh only; never replay upsert/delete to fix a read. Preserve generation ownership and CTS disposal from SEC-01. +4. Add delayed initial load, metadata-only Retry, mutation-committed/reload-failed and disposed-load tests. Run `dotnet test tests/ZB.MOM.WW.Secrets.Ui.Tests/ZB.MOM.WW.Secrets.Ui.Tests.csproj`; expected PASS, especially `AuditFailureAfterCommitTests` and reveal fail-closed tests. +5. Stage the three named files; commit `fix(secrets-ui): distinguish list recovery from committed mutations`. + +## SEC-05 · Improve metadata scanning and row-action context + +**Covers:** SEC-04; DS-01/05. **Depends:** G1 + SEC-01–04. + +**Modify:** `src/ZB.MOM.WW.Secrets.Ui/Components/SecretsList.razor`; `src/ZB.MOM.WW.Secrets.Ui/Components/RevealButton.razor`; `tests/ZB.MOM.WW.Secrets.Ui.Tests/SecretsListTests.cs`. + +1. Add a behavior regression inside `SecretsListTests`, reusing `RegisterStore`/`SecretOne`/`SecretTwo`: + +```csharp +[Fact] +public void NameFilter_CanBeClearedWithoutHidingMetadataPermanently() +{ + RegisterStore(SecretOne, SecretTwo); + var cut = Render(); + cut.Find("input[data-testid=secret-filter]").Input("db/primary"); + Assert.Single(cut.FindAll("tbody tr[data-secret-row]")); + cut.Find("[data-testid=clear-secret-filter]").Click(); + Assert.Equal(2, cut.FindAll("tbody tr[data-secret-row]").Count); +} +``` + +2. Run `dotnet test tests/ZB.MOM.WW.Secrets.Ui.Tests/ZB.MOM.WW.Secrets.Ui.Tests.csproj --filter FullyQualifiedName~NameFilter_CanBeClearedWithoutHidingMetadataPermanently`; expected FAIL: no filter. +3. Add a visibly labelled local name filter (metadata already loaded, no value access), clear action and zero-match state. Keep name/description/update time prominent. Move KEK/revision/type/by into native details or responsive secondary cells without deleting metadata. Name each action with its row target (“Rotate app/a”); use a real Actions header and proper row/header semantics. Preserve manage/reveal policies both in markup and handlers. +4. Add no-match/clear, long-name and accessible action-context tests; run `--filter FullyQualifiedName~SecretsListTests`, expected PASS. Inspect 390px, 1440px, 200% zoom, keyboard, long unbroken names and multiple simultaneous rows. The document may not overflow; scoped table/payload scrolling is acceptable. Layout-only changes need visual checks, not tests counting CSS classes. +5. Stage the three named files; commit `feat(secrets-ui): add metadata filtering and clear row actions`. + +## SEC-06 · Keep reveal outcomes discoverable without announcing plaintext + +**Covers:** SEC-05; DS-04. **Depends:** SEC-05 + G1 busy/focus recipe. + +**Modify:** `src/ZB.MOM.WW.Secrets.Ui/Components/RevealButton.razor`; `tests/ZB.MOM.WW.Secrets.Ui.Tests/RevealButtonTests.cs`; `tests/ZB.MOM.WW.Secrets.Ui.Tests/RevealAuditFailureTests.cs`. + +1. Extend `RevealButtonTests` with a regression using the same fake registrations as its existing reveal test: seed `cipher.Encrypt(new SecretName("app/a"), "synthetic-value", SecretContentType.Text)`, authorize RevealPolicy, render Name app/a, click `[data-testid=reveal-button]`. Add these assertions: + +```csharp +cut.WaitForAssertion(() => +{ + var status = cut.Find("[data-testid=reveal-status][role=status]"); + Assert.Contains("Value revealed", status.TextContent); + Assert.DoesNotContain("synthetic-value", status.TextContent); +}); +cut.Find("[data-testid=hide-button]").Click(); +Assert.Empty(cut.FindAll("[data-testid=revealed-value]")); +``` + +2. Run `dotnet test tests/ZB.MOM.WW.Secrets.Ui.Tests/ZB.MOM.WW.Secrets.Ui.Tests.csproj --filter FullyQualifiedName~RevealButtonTests`; expected FAIL in the new regression on absent outcome status. +3. Keep a stable non-sensitive outcome region and a logically stable trigger/Hide focus path. Announce reveal success/failure only, never plaintext. Clear rendered value on Hide; preserve audit-before-disclosure and handler authorization. Do not add auto-hide without an explicit product policy: current review proposes evaluation, not a mandate. Document the chosen “visible until Hide/navigation” behavior in local help for this release. +4. Run the named RevealButtonTests/RevealAuditFailureTests filters and entire UI suite; expected PASS. Browser-test keyboard reveal/error/hide with synthetic data. Inspect accessibility tree and audit payload to ensure plaintext occurs only in the intentional rendered value, never live status, labels, URL or event details. Use no real-secret screenshot. +5. Stage the three named files; commit `fix(secrets-ui): announce reveal outcomes without disclosing values`. + +## SEC-07 · Package and host integration evidence + +**Covers:** SEC-01–06, DS-06. **Depends:** all tasks + G1. + +**Modify at version-selection time:** `src/ZB.MOM.WW.Secrets.Ui/ZB.MOM.WW.Secrets.Ui.csproj`, `README.md`; modify `Directory.Build.props` only if deliberately coordinating a complete dependency release. +**Create:** `docs/ui-consistency-validation.md`. + +1. Run `dotnet build src/ZB.MOM.WW.Secrets.Ui/ZB.MOM.WW.Secrets.Ui.csproj -c Release`; expected zero new warnings. +2. Run `dotnet test tests/ZB.MOM.WW.Secrets.Ui.Tests/ZB.MOM.WW.Secrets.Ui.Tests.csproj -c Release`; expected all tests pass, including authorization, audit-failure-after-commit and reveal-audit-failure suites. Record restored Theme/transitive dependencies. +3. Exercise packaged UI in OtOpcUa's per-page-interactive wrapper and another Bootstrap/global-interactive host using synthetic values. Verify no duplicate `/admin/secrets` route, dead @onclick, missing scoped assets or Bootstrap modal collision. Verify manages-only/reveals-authorized/denied, empty/load/reload failure, target switches, long names, 390/1440px, zoom, reduced motion and actual modal focus. Cross-check shared recipes against the OtOpcUa dialog pilot before extracting generic code. +4. Choose the smallest valid package release set. Prefer a UI-only project-level `` override in `src/ZB.MOM.WW.Secrets.Ui/ZB.MOM.WW.Secrets.Ui.csproj`, leaving the shared `Directory.Build.props` version and Abstractions unchanged. A global version bump would also change the UI's ProjectReference-derived Abstractions dependency; UI-only packing would then reference a possibly unpublished package. Verify the exact Abstractions version exists in the feed. If it does not, coordinate the minimal dependency package set explicitly; do not assume a global version number implies every package is available. Document the actual Theme lower bound and host adoption order. +5. Commit the source/version changes before packing, recording a clean committed source identity. Run `dotnet pack src/ZB.MOM.WW.Secrets.Ui/ZB.MOM.WW.Secrets.Ui.csproj -c Release -o artifacts/ui-consistency`; expected a local new immutable `SECRETS_UI_VERSION` artifact. If a coordinated Abstractions package is required, also run `dotnet pack src/ZB.MOM.WW.Secrets.Abstractions/ZB.MOM.WW.Secrets.Abstractions.csproj -c Release -o artifacts/ui-consistency`. Inspect each `.nuspec` inside its `.nupkg` for actual ID/version/Theme/Abstractions dependencies; record SHA-256 and repository commit. Do not infer dependency versions from folder names. +6. Verify an isolated restore before feed publication. Create a disposable `/tmp/scada-ui-consistency-secrets-restore/UiSmoke.csproj` with `Microsoft.NET.Sdk.Web`, `net10.0`, and PackageReferences to the exact selected UI and Theme versions, plus a minimal `Program.cs` containing `WebApplication.CreateBuilder(args).Build().Run();` with the ASP.NET builder using. Run `dotnet restore /tmp/scada-ui-consistency-secrets-restore/UiSmoke.csproj --packages /tmp/scada-ui-consistency-secrets-restore/packages --source /Users/dohertj2/Desktop/scadaproj/ZB.MOM.WW.Secrets/artifacts/ui-consistency --source ACTUAL_APPROVED_FEED_URL` with the existing authenticated feed configuration; substitute the actual URL rather than commit that placeholder. Include every other approved configured package source needed by the dependency graph, including the approved public source when required: explicit `--source` flags override source selection. Keep the isolated package directory empty initially so success is not masked by a developer global package cache. Run `dotnet build /tmp/scada-ui-consistency-secrets-restore/UiSmoke.csproj --no-restore`; expected restore/build success using the exact minimal package set, with no fallback to an unintended source build. Inspect `obj/project.assets.json` and record the resolved graph. +7. After the master release gate and later explicit authorization, publish only the exact validated package set through the established package release process. Download those feed artifacts into a separate empty verification directory, compare SHA-256 to the validated local artifacts, and repeat isolated restore against the feed without the local package source. Consumer package-pin adoption remains blocked until this succeeds. No publication or deployment occurs while writing or reviewing this plan. +8. Record validation, checksums, dependency graph, actual versions and screenshot links in the validation doc; finish Impeccable audit/polish. Stage only readme/validation updates and commit `docs(secrets-ui): record package and host UI acceptance gates`. + +## Complete finding coverage + +| Review finding | Plan task | Shared contract | +|---|---|---| +| SEC-06 target/draft leakage | SEC-01, SEC-07 | local state identity; independent of G1 | +| SEC-01 unnamed fields | SEC-02, SEC-07 | DS-01/02/04/06 | +| SEC-02 dialog name/focus | SEC-03, SEC-07 | DS-04/05 | +| SEC-03 loading/refresh recovery | SEC-04, SEC-07 | DS-04/05 | +| SEC-04 metadata/action context | SEC-05, SEC-07 | DS-01/05 | +| SEC-05 reveal feedback | SEC-06, SEC-07 | DS-04 | + +## Rollout and rollback + +This chapter prepares source, tests, package and host acceptance only. Consumers adopt `SECRETS_UI_VERSION` and `THEME_VERSION` through their own reviewed package pins after gates. Keep the previous immutable library/host artifacts and restored graphs. Roll back package/host assets together; do not undo tombstones, rotate credentials, replay mutations or change encryption/storage formats as a visual rollback. If target isolation is fixed independently, preserve that correction rather than reverting it with later aesthetic work. No data migration is planned. diff --git a/docs/plans/2026-11-12-scada-ui-consistency/Theme.md b/docs/plans/2026-11-12-scada-ui-consistency/Theme.md new file mode 100644 index 0000000..7b1940e --- /dev/null +++ b/docs/plans/2026-11-12-scada-ui-consistency/Theme.md @@ -0,0 +1,358 @@ +# Shared Technical-Light Theme Implementation Plan + +> **For Codex:** REQUIRED SUB-SKILL: Use `executeplan` to implement this plan task-by-task. + +**Goal:** Make readable state text, labeled fields, complete accent states, focus, busy feedback and reusable interaction recipes consistent across every sister UI before local visual migration. + +**Architecture:** Evolve the existing Razor Class Library; do not replace its shell or copy mockup CSS into applications. Add compatible component parameters and semantic text tokens, retaining existing signal colors and SSR behavior. Publish one reviewed package and migrate consumers against the same contract. + +**Tech Stack:** .NET 10 Razor Class Library, Bootstrap 5 consumer utilities, CSS custom properties, IBM Plex, xUnit 2.9.3, bUnit 2.7.2 (`BunitContext` / `Render`), GB-validated AngleSharp family (pre-GB direct pin 1.5.0), existing Node script tests. + +--- + +## 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. + +## Baseline and boundaries + +- Repository: `/Users/dohertj2/Desktop/scadaproj`; library root: `/Users/dohertj2/Desktop/scadaproj/ZB.MOM.WW.Theme`. +- Current library source: **0.5.3** in `Directory.Build.props`. The parent repository advanced after the review only in telemetry/observability files; Theme source did not change. +- Inputs: [shared recommendations](../../../impeccable/SHARED-DESIGN-SYSTEM.md), [Theme report](../../../impeccable/Theme.md), [component concept](../../../impeccable/mockups/Theme.html), [contrast evidence](../../../impeccable/evidence/contrast.json). +- Read the [master plan](../2026-11-12-scada-ui-consistency.md) before executing. G1 is this chapter's release gate; all named versions in dependent chapters remain placeholders until release decisions are recorded. +- Preserve Plex, warm paper, white surfaces, existing 8px panels, 220px desktop rail, native mobile disclosure, nav state persistence, current button class composition, `ScrollNav`, and stateless `TreeTable` behavior. +- This chapter plans changes. Tests, builds, package publication and deployments have not been run as part of planning. + +Paths below are relative to the library root unless prefixed with `/Users/`. All shell blocks state their working directory. New test files are proposed; existing files have been checked. Every step is a separate small action; repeat a step per component family rather than combining the family into an unreviewable edit. + +## Contract supplied at G1 + +| Contract | Exact decision | +|---|---| +| Text inks | Add `--ok-ink:#236f34`, `--bad-ink:#b42121`, `--idle-ink:#535d66`; set existing `--warn-ink:#855000`, `--ink-faint:#626970` | +| Signal colors | Retain `--ok`, `--warn`, `--bad`, `--idle` for dots/stripes/charts; route small text through semantic inks | +| Accent | Keep `Accent`; add optional `AccentDeep`, `AccentTint`, `AccentBorder`, `AccentFocus`; emit `--accent-deep`, `--accent-tint`, `--accent-border`, `--accent-focus` only when supplied | +| Semantic info | Add `--info-ink` with the existing blue deep value; informational status remains deliberately independent of brand accent | +| Fields | Optional `For`, `HintId`, `ErrorId` on `TechField`; caller controls input `id`, `aria-describedby`, `aria-invalid`; no guessing an arbitrary ChildContent control | +| Busy action | Optional `BusyText`; `aria-busy` reflects `Busy`; keep Type, disabled and attribute/class behavior intact; caller owns a separate outcome status region | +| Focus/motion | Visible focus for all shared interactive controls; reduced motion shows final content immediately and retains text state | +| Recipes | Labeled filter, table sort/disclosure, empty/error/freshness and managed confirmation examples; domain behavior remains local | +| Version | `THEME_VERSION` selected under the documented token compatibility policy; never publish over 0.5.3 or assume a minor version | + +A full family dark theme is not a prerequisite for G1. Preserve each application's explicitly supported scheme and require new semantic aliases there; do not claim family dark support from one application's overrides. Record additional dark-theme expansion as separate work. + +## Task TH-01: Capture post-GB baseline and Theme compatibility decisions (DS-06) + +**Files:** +- Read: `Directory.Build.props`, `Directory.Packages.props`, `README.md`, `src/ZB.MOM.WW.Theme/Components/ThemeShell.razor`. +- Create: `/Users/dohertj2/Desktop/scadaproj/components/ui-theme/RELEASE-DECISION.md`. +- Modify later: `/Users/dohertj2/Desktop/scadaproj/components/ui-theme/GAPS.md`. + +1. Record branch, commit and existing changes; use a suitable checkout/branch with prefix `codex/` without overwriting unrelated work. Re-read applicable repository instructions. +2. Establish the unchanged baseline from library root: + + ```bash + dotnet build ZB.MOM.WW.Theme.slnx -c Release + dotnet test tests/ZB.MOM.WW.Theme.Tests/ZB.MOM.WW.Theme.Tests.csproj -c Release --no-build + ``` + + Expected: existing build/tests pass, warnings remain errors. Record actual counts; do not copy historical totals. If restore/feed failure occurs, record it as infrastructure failure, not a test failure. +3. Record actual consumer pins and transitive resolution using the master adoption matrix. Inspect authored `.btn` usages as well as local sizing definitions: a selector can exist but match no consumer markup. +4. State that current policy treats token changes as breaking. Select a version consistent with that policy; document any deliberate policy revision before assigning `THEME_VERSION`. Component parameter additions alone do not justify silently overriding token policy. +5. Record light/dark scheme support, default/green/teal/purple accent inputs and a zero-domain-behavior-change boundary. +6. Commit only the release-decision record: `docs(theme): define accessible theme release contract`. + +**Exit:** GB is closed, the post-migration baseline and explicit Theme compatibility decision exist; no release has yet occurred. + +## Task TH-02: Introduce readable semantic text inks (DS-01) + +**Files:** +- Modify: `src/ZB.MOM.WW.Theme/wwwroot/css/theme.css` and `src/ZB.MOM.WW.Theme/wwwroot/css/layout.css`. +- Create test: `tests/ZB.MOM.WW.Theme.Tests/ThemeTokenContrastTests.cs`. +- Modify existing test: `tests/ZB.MOM.WW.Theme.Tests/StaticAssetsTests.cs` (replace the old `--idle` text assertion with `--idle-ink`; keep background and asset protections). +- Modify docs: `/Users/dohertj2/Desktop/scadaproj/components/ui-theme/spec/DESIGN-TOKENS.md`. + +1. Add a behavioral token-pair contrast test. Complete starting test class: + + ```csharp + using System.Globalization; + using System.Text.RegularExpressions; + namespace ZB.MOM.WW.Theme.Tests; + public sealed class ThemeTokenContrastTests + { + private static string Css => File.ReadAllText(Path.GetFullPath(Path.Combine( + AppContext.BaseDirectory, "..", "..", "..", "..", "..", + "src", "ZB.MOM.WW.Theme", "wwwroot", "css", "theme.css"))); + private static string Token(string name) + { + var match = Regex.Match(Css, Regex.Escape(name) + @"\s*:\s*(#[0-9a-fA-F]{6})\s*;"); + Assert.True(match.Success, $"Missing hex token {name}"); + return match.Groups[1].Value; + } + private static double Luminance(string hex) + { + double Channel(int start) + { + var value = int.Parse(hex.Substring(start, 2), NumberStyles.HexNumber, + CultureInfo.InvariantCulture) / 255d; + return value <= .04045 ? value / 12.92 : Math.Pow((value + .055) / 1.055, 2.4); + } + return .2126 * Channel(1) + .7152 * Channel(3) + .0722 * Channel(5); + } + private static double Ratio(string a, string b) + { + var x = Luminance(a); var y = Luminance(b); + return (Math.Max(x, y) + .05) / (Math.Min(x, y) + .05); + } + [Theory] + [InlineData("--ok-ink", "--ok-bg")] + [InlineData("--warn-ink", "--warn-bg")] + [InlineData("--bad-ink", "--bad-bg")] + [InlineData("--idle-ink", "--idle-bg")] + [InlineData("--ink-faint", "--paper")] + [InlineData("--ink-faint", "--card")] + public void Small_text_pairs_meet_AA(string foreground, string background) => + Assert.True(Ratio(Token(foreground), Token(background)) >= 4.5); + [Fact] + public void Contrast_reference_is_black_on_white() => + Assert.Equal(21d, Ratio("#000000", "#ffffff"), 6); + } + ``` + +2. Run from library root: + + ```bash + dotnet test tests/ZB.MOM.WW.Theme.Tests/ZB.MOM.WW.Theme.Tests.csproj --filter FullyQualifiedName~ThemeTokenContrastTests + ``` + + Expected red: missing semantic tokens and inadequate current warning/faint contrast; the black/white reference passes. +3. Add/update only the token values in the G1 contract. Retain signal-color values. +4. Migrate foreground declarations, one group per edit: `.chip-*`, `.s-*`, `.conn-pill[data-state]`, `.kv .v.*`, aggregate caution/alert/success text and notices. Do not replace dot/stripe/background colors mechanically. Use `--info-ink` for semantic informational text. Keep identifiers and state labels textual. +5. Update the old idle-foreground assertion and token documentation to express the new semantic contract. Do not “fix” the failing contrast test by lowering its threshold. +6. Run the targeted tests, then the full Theme test project. Expected green. In a real consumer, measure computed chip/notice/value text including opacity; token math alone cannot prove selector application. +7. Commit: `fix(theme): make shared status and supporting text readable`. + +**Acceptance:** current backgrounds plus semantic text pairs are ≥4.5:1; no brighter signal colors are lost; no CSS literals outside the token authority are added. Test coverage verifies contrast behavior, not a snapshot of every CSS declaration. + +## Task TH-03: Associate TechField labels and descriptions (DS-02) + +**Files:** +- Modify: `src/ZB.MOM.WW.Theme/Components/TechField.razor`. +- Create test: `tests/ZB.MOM.WW.Theme.Tests/TechFieldAssociationTests.cs`. +- Retain: `tests/ZB.MOM.WW.Theme.Tests/CommonControlsTests.cs`. +- Modify: `README.md` (caller ID/ARIA usage). + +1. Add this red bUnit case under `TechFieldAssociationTests : BunitContext`: + + ```csharp + [Fact] + public void Field_connects_label_hint_and_error_to_the_callers_input() + { + var cut = Render(p => p + .Add(x => x.Label, "Name").Add(x => x.For, "secret-name") + .Add(x => x.Hint, "Use a stable name").Add(x => x.HintId, "name-hint") + .Add(x => x.Error, "Name is required").Add(x => x.ErrorId, "name-error") + .AddChildContent("")); + Assert.Equal("secret-name", cut.Find("label").GetAttribute("for")); + Assert.Equal("Use a stable name", cut.Find("#name-hint").TextContent); + Assert.Equal("Name is required", cut.Find("#name-error").TextContent); + Assert.Equal("name-hint name-error", cut.Find("input").GetAttribute("aria-describedby")); + } + ``` + +2. Run from library root: `dotnet test tests/ZB.MOM.WW.Theme.Tests/ZB.MOM.WW.Theme.Tests.csproj --filter FullyQualifiedName~TechFieldAssociationTests`. Expected red initially: missing new parameters. +3. Add nullable string parameters `For`, `HintId`, `ErrorId`; render `for="@For"`, `id="@HintId"`, `id="@ErrorId"` on the existing label/hint/error. Emit hint/error only when their content exists. Do not insert nested labels or rewrite arbitrary ChildContent. +4. Add two related tests: no error node when Error is absent; two fields with explicitly different IDs remain independent. Old consumers with no new parameters still render without exceptions. +5. Document exact consumer usage: + + ```razor + + + + ``` + + When an error appears, the caller appends its ErrorId to `aria-describedby` and sets `aria-invalid`; do not include IDs of absent nodes. Use stable per-instance IDs for repeated forms. +6. Run targeted then full tests. Browser acceptance: clicking a label focuses its control; a screen reader names the field and reads associated help/error once. Keep focus-on-error and error announcements local to the form. +7. Commit: `feat(theme): associate field labels and descriptions`. + +## Task TH-04: Carry the whole product accent through interaction states (DS-03) + +**Files:** +- Modify: `src/ZB.MOM.WW.Theme/Components/ThemeShell.razor`. +- Modify: `src/ZB.MOM.WW.Theme/wwwroot/css/theme.css`, `src/ZB.MOM.WW.Theme/wwwroot/css/layout.css`. +- Modify test: `tests/ZB.MOM.WW.Theme.Tests/ThemeShellTests.cs`. +- Modify docs: `README.md`, `/Users/dohertj2/Desktop/scadaproj/components/ui-theme/spec/DESIGN-TOKENS.md`. + +1. Add a red render test with `Accent="#2f855a"`, `AccentDeep="#1c6540"`, `AccentTint="#edf5f0"`, `AccentBorder="#bddbc9"`, `AccentFocus="#1c6540"`; assert all five intended CSS variables occur on `.app-shell`. Keep the existing no-accent/no-style and Accent-only tests. +2. Run from library root: `dotnet test tests/ZB.MOM.WW.Theme.Tests/ZB.MOM.WW.Theme.Tests.csproj --filter FullyQualifiedName~ThemeShellTests`. Expected red: additive parameters missing. +3. Add optional parameters and compose only supplied values. Keep `Accent` behavior backward-compatible. Add default `--accent-tint`, `--accent-border`, `--accent-focus`; use `var(--accent-tint)` directly in active selectors (or rebind `--active-bg:var(--accent-tint)` on `.app-shell`), interactive borders through `--accent-border`, and focus through `--accent-focus`. Do not rely on an alias resolved in `:root` to pick up a child shell override: inherited custom-property values can already be computed there. + Also bind Bootstrap component variables at the actual component scope. Bootstrap `.btn-primary` hard-codes its own button colors; changing root `--bs-primary` alone does not recolor it. Add `--on-accent:#ffffff` in the canonical token block, verify each approved accent supports readable white text, and map the primary/ghost components without disturbing button sizing/group seams. Minimum primary mapping: + + ```css + .btn-primary { + --bs-btn-color: var(--on-accent); + --bs-btn-bg: var(--accent); + --bs-btn-border-color: var(--accent); + --bs-btn-hover-color: var(--on-accent); + --bs-btn-hover-bg: var(--accent-deep); + --bs-btn-hover-border-color: var(--accent-deep); + --bs-btn-active-color: var(--on-accent); + --bs-btn-active-bg: var(--accent-deep); + --bs-btn-active-border-color: var(--accent-deep); + --bs-btn-disabled-color: var(--on-accent); + --bs-btn-disabled-bg: var(--accent); + --bs-btn-disabled-border-color: var(--accent); + } + .btn-link { --bs-btn-color: var(--accent); --bs-btn-hover-color: var(--accent-deep); } + ``` + + Check existing local primary/ghost overrides before deletion. Use the shared visible outline for primary focus and remove an inherited blue-only Bootstrap focus shadow where it conflicts; do not remove all focus feedback. Cover normal/hover/pressed/disabled and selected table actions in the browser computation check. + +4. Preserve independent informational blue: `--info-ink` and `--info-bg` are semantic info colors, not automatically product accent. Test actual contrast instead of assuming green/purple substitutions are safe. +5. Verify nested subtree scope and a page with no per-product override. Ensure no inline style is emitted when all parameters are absent; no style parameter accepts untrusted remote input. +6. Browser-compare default blue, Historian green, BTDB teal and Overview purple, including hover/active/focus. Assert the actual computed active background equals each supplied tint; checking inline custom-property text alone misses root-scope alias resolution. Record approved exact tint/deep/border values in the adoption matrix. +7. Run the targeted and full tests; commit `feat(theme): support complete product accent states`. + +## Task TH-05: Complete busy feedback without changing disabled semantics (DS-04) + +**Files:** +- Modify: `src/ZB.MOM.WW.Theme/Components/TechButton.razor`. +- Modify test: `tests/ZB.MOM.WW.Theme.Tests/TechButtonExtensionsTests.cs`. +- Modify docs: `README.md`. + +1. Add a red test rendering Busy=true/BusyText="Saving changes…"; assert disabled, `aria-busy="true"` and visible busy text, then render Busy=false and assert original child label returns. Preserve the existing tests for caller disabled, class composition, Type and click behavior. +2. Run: `dotnet test tests/ZB.MOM.WW.Theme.Tests/ZB.MOM.WW.Theme.Tests.csproj --filter FullyQualifiedName~TechButtonExtensionsTests` from library root. Expected red: missing parameter/state attribute. +3. Add optional `BusyText`; when busy and nonempty show that text, otherwise preserve ChildContent. Render explicit `aria-busy`; keep spinner decorative. Retain `Busy || CallerDisabled` and current class merging. +4. Document a caller-owned, persistent `role="status"` region for operation completion/failure. Never put secret values or every polling update in it. Do not attach a global assertive live region to every button. +5. Run targeted/full tests; browser-check slow success, slow failure, caller-disabled and keyboard focus after completion. Commit `feat(theme): expose accessible busy action state`. + +## Task TH-06: Focus, reduced motion and responsive recipes (DS-04/05) + +**Files:** +- Modify: `src/ZB.MOM.WW.Theme/wwwroot/css/theme.css`, `src/ZB.MOM.WW.Theme/wwwroot/css/layout.css`. +- Create docs: `/Users/dohertj2/Desktop/scadaproj/components/ui-theme/spec/INTERACTION-RECIPES.md`. +- Modify: `README.md`. + +1. In the two pilot consumers described in the master plan, establish a failing browser observation: an affected custom control lacks a clear focus treatment or a `.rise` element animates with reduced motion. Save the before evidence with the route/commit, not just a CSS grep. +2. Add a shared `:focus-visible` rule using `--accent-focus`, leaving existing stronger specialized focus handling intact. Use an intentional outline width/offset; check clipping inside scroll regions. +3. Add `prefers-reduced-motion: reduce` for `.rise` to render the final state immediately; replace pulse with a stable connection state. Avoid a global 0.01ms animation override. +4. Document semantic recipes with complete minimal examples: labeled filter and clear action, table caption/headers/scroll region, sortable header button and `aria-sort`, true row disclosure button with `aria-expanded`, empty vs failed vs stale state, and a confirmation focus lifecycle. +5. For example, a table action must use the real input path: + + ```razor + + + + ``` + + `ToggleSort` must sort the actual displayed dataset and preserve selection. A cursor alone is not sorting; keep domain sorting logic in the consumer. +6. Specify the dialog contract: associated heading/description; initial safe focus; Tab/Shift+Tab within visible enabled controls; real DOM keydown event and `preventDefault`; safe Escape; inert background; focus return; busy-close rules. Reuse an existing strong implementation for each pilot; no `window.event` across asynchronous Blazor interop. A native dialog is allowed only after host/browser suitability is verified. +7. Run real-browser checks at 1440×900, 1024×768 and 390×844, actual 200% zoom, keyboard and reduced motion. Test mobile nav both open and closed: content must stay visible, focus reachable, tables scroll internally. No new unit tests merely asserting a CSS declaration. +8. Commit `feat(theme): standardize focus motion and interaction recipes`. + +**Exit:** recipes work in two representative host modes. G1 does not require a new generic modal component; extracting one has a separate evidence gate G2. + +## Task TH-07: Documentation, package contents and local canary (DS-06) + +**Files:** +- Modify: `Directory.Build.props`, `README.md`. +- Modify docs: `/Users/dohertj2/Desktop/scadaproj/components/ui-theme/README.md`, `/Users/dohertj2/Desktop/scadaproj/components/ui-theme/spec/SPEC.md`, `/Users/dohertj2/Desktop/scadaproj/components/ui-theme/spec/DESIGN-TOKENS.md`, `/Users/dohertj2/Desktop/scadaproj/components/ui-theme/shared-contract/ZB.MOM.WW.Theme.md`, `/Users/dohertj2/Desktop/scadaproj/components/ui-theme/GAPS.md`. +- Create release evidence: `/Users/dohertj2/Desktop/scadaproj/components/ui-theme/releases/THEME_VERSION.md` (substitute the actual selected version in the filename). +- Read scripts: `build/pack.sh`, `build/push.sh`; do not blindly publish all existing artifacts. + +1. Resolve `THEME_VERSION` from TH-01, update source version once and correct obsolete “not started,” version, asset and JavaScript statements in adoption docs. Include a parameter migration example and semantic-token migration table. +2. Commit reviewed source/version changes before the final package build, verify a clean source tree, and record that exact commit as the package source revision. Documentation-only validation evidence can be committed separately afterward. Run from library root: + + ```bash + dotnet build ZB.MOM.WW.Theme.slnx -c Release + dotnet test tests/ZB.MOM.WW.Theme.Tests/ZB.MOM.WW.Theme.Tests.csproj -c Release --no-build + ./build/pack.sh + ``` + + Expected: clean build, all tests green and exactly the intended version package newly produced. Do not use baseline test totals as a target. +3. Inspect the exact `.nupkg` with `unzip -l artifacts/ZB.MOM.WW.Theme..nupkg`. Expected: DLL, CSS, fonts, nav-state script and correct static-web-assets metadata; no unrelated package. Record `shasum -a 256` for that exact artifact. +4. Use an isolated local NuGet source to restore that package into Overview and one large consumer pilot (ScadaBridge), without changing deployment credentials or replacing existing production packages. `dotnet restore --source --source ` must use existing feed credentials/config and include all other approved configured sources needed for public dependencies; explicit `--source` options override source selection. Do not diagnose a missing public dependency as a UI regression after accidentally omitting its approved source. Verify project.assets.json resolves the intended Theme version and one font/CSS authority. +5. Complete pilot tests and the master visual matrix. If a pilot failure requires a Theme change, fix/retest that affected task before release; do not hide the failure with local override copies. +6. Commit acceptance documentation: `docs(theme): document and validate the shared UI release`. The package must remain the byte-verified output from the clean source/version commit in step 2; do not relabel its source revision with this later evidence-only commit. + +## Task TH-08: Export canonical static assets for public-feed-only and native consumers (DS-05/06) + +**Files:** +- Create: `build/export-web-assets.py` and `build/test_export_web_assets.py`. +- Modify: `README.md` and release evidence. +- Output (generated, exact version): `artifacts/technical-light-web-assets..zip`. + +**Why:** ignitionoee registry explicitly permits only public NuGet dependencies. Do not introduce a private Theme package prerequisite. Perspective needs native JSON styles, not Blazor components. Export from the already validated package bytes, not from a second hand-maintained palette. + +1. Write `unittest` cases in `build/test_export_web_assets.py` using a synthetic input nupkg: byte-for-byte CSS/font parity, correct package ID/version and source hash, complete required asset set, missing-asset refusal, and deterministic repeated export. Assert a changed input CSS byte changes its manifest hash. These are artifact-integrity behavior tests, not CSS declaration snapshots. +2. Run from library root: `python3 -m unittest discover -s build -p 'test_export_web_assets.py' -v`. Expected red: exporter missing. Keep tests offline; use temporary files and synthetic package fixtures. +3. Implement an explicit `--package`, `--source-revision`, `--source-tag`, `--output` CLI using Python standard library `zipfile`, `hashlib`, `json`, `re`, `argparse`, `xml.etree.ElementTree`. Read the input package's nuspec; refuse a package ID other than `ZB.MOM.WW.Theme`. Derive version from nuspec, not the output filename. Refuse missing required static assets; do not silently skip them. +4. Copy these package entries to the export root without altering bytes: + + | Nupkg prefix / entry | Export root | + |---|---| + | `staticwebassets/css/theme.css` | `css/theme.css` | + | `staticwebassets/css/layout.css` | `css/layout.css` | + | `staticwebassets/fonts/ibm-plex-sans-400.woff2` | `fonts/ibm-plex-sans-400.woff2` | + | `staticwebassets/fonts/ibm-plex-sans-600.woff2` | `fonts/ibm-plex-sans-600.woff2` | + | `staticwebassets/fonts/ibm-plex-mono-500.woff2` | `fonts/ibm-plex-mono-500.woff2` | + + Entry paths above were verified in existing Theme packages. Verify them again for the actual new package. No consumer needs a private-feed restore to use this zip. +5. Generate `tokens.json` from the canonical `:root` declarations after stripping CSS comments. Use the exact shape `{ "schemaVersion": 1, "themeVersion": "", "tokens": { "--paper": "#f4f4f1", "--active-bg": "var(--accent-tint)" } }` with every canonical root token in the tokens object. Preserve raw token values and references; include schema version and Theme version. Native consumers select/resolve the semantic tokens they support; do not claim the parser implements arbitrary CSS. Refuse malformed/missing required semantic tokens. +6. Generate `manifest.json` with this contract (example values are placeholders): + + ```json + { + "schemaVersion": 1, + "themeVersion": "", + "sourcePackage": "ZB.MOM.WW.Theme", + "sourcePackageSha256": "", + "sourceRevision": "", + "sourceTag": "", + "files": { + "css/theme.css": "", + "css/layout.css": "", + "fonts/ibm-plex-sans-400.woff2": "", + "fonts/ibm-plex-sans-600.woff2": "", + "fonts/ibm-plex-mono-500.woff2": "", + "tokens.json": "" + } + } + ``` + + Hash all payload files before serializing the manifest; do not put a self-hash into the manifest. Use stable zip ordering/timestamps so identical inputs produce identical output. Reject path traversal entries and unexpected duplicate required entries when reading the zip. +7. Run the artifact tests green. Generate the export from the exact TH-07 nupkg, passing the recorded source revision/tag; record the export's sha256 beside the package's hash. Independently unpack and recompute every payload hash. Source revision must correspond to the reviewed clean package build; do not fill metadata from a different checkout. +8. For a limited pre-G1 candidate pilot, have registry restore its current public-feed graph unchanged, import the export into `registry/src/Registry.Host/wwwroot/shared-theme/`, and validate fonts/CSS/manifest paths in its pilot. It may consume `theme.css` and keep its domain selectors; load `layout.css` only where actual matching markup and dependencies have been verified. +9. Commit exporter/tests/docs: `build(theme): export versioned canonical web assets`. Store/publish the exact zip through the agreed artifact delivery channel; record immutable filename/hash, not a mutable URL alone. + +**Exit:** package and static-export parity are proven. G1 cannot close for the whole family without this export. Registry and Perspective chapters own import/native mapping, not the Theme RCL. + +## Task TH-09: Publish G1 and govern shared extraction (DS-05/06) + +**Files:** release evidence and the shared adoption matrix in the master plan; consumer version files belong to later chapters. + +1. After the reviewed package and local canary pass, publish only the exact validated `.nupkg` using the repository's configured feed and existing credential environment. Execution must have package-publication authorization; this planning request does not publish anything. Never repack/reuse an immutable version or push a wildcard containing other packages. +2. Download that version from the feed independently, compare hash with TH-07, and verify one consumer restores it without the local source. Record actual `THEME_VERSION` and artifact hash. Record the verified TH-08 static export alongside it. This closes **G1**. +3. Continue shared Secrets UI and consumer adoption in master order. Hold the exact prior app artifact/package lock for rollback; keep backend schema/protocol behavior unchanged. +4. After two completed dialog pilots, compare the duplicated behavior. If they share a stable API, make a separate task/release to extract the helper/component into Theme. Add two-host browser contract tests before switching callers. If not, retain validated local adapters and shared recipes; do not create a speculative abstraction. +5. Record **G2** (common interaction recipe verified in at least two consumers, with an extraction decision) without making generic extraction a prerequisite for already safe local repairs. +6. Commit release evidence: `docs(theme): record release and consumer pilot results`. + +## Finding coverage and exit checklist + +| Finding | Tasks | Required evidence | +|---|---|---| +| DS-01 | TH-02, TH-07 | Pair tests + computed-style/state captures | +| DS-02 | TH-03, Secrets caller migration | Rendered label relationships + browser name/focus | +| DS-03 | TH-04, all consumer adoption tasks | Four accent families across default/hover/active/focus | +| DS-04 | TH-05/06 | Busy/disabled tests, keyboard and reduced motion | +| DS-05 | TH-06/08/09 | Two consumer interaction pilots, no domain imports | +| DS-06 | TH-01/07/08/09 | Explicit compatibility/version, hash, restore graph, adoption ledger | + +- [ ] G1 package immutable and independently verified; exact version resolved. +- [ ] Theme full tests and both pilots green; findings tied to actual current source. +- [ ] Colors, type, space, borders and state semantics match the shared contract across accents. +- [ ] Login remains static POST with host antiforgery and safe return URL; TreeTable ownership unchanged. +- [ ] Existing supported dark scheme remains readable; no claim of unsupported family dark behavior. +- [ ] Rollback artifact/version identified; no incompatible backend changes bundled. +- [ ] Final @impeccable audit evidence and bounded @impeccable polish recorded after implementation. diff --git a/docs/plans/2026-11-12-scada-ui-consistency/bunit-inventory.json b/docs/plans/2026-11-12-scada-ui-consistency/bunit-inventory.json new file mode 100644 index 0000000..06279a1 --- /dev/null +++ b/docs/plans/2026-11-12-scada-ui-consistency/bunit-inventory.json @@ -0,0 +1,141 @@ +{ + "schemaVersion": 1, + "scope": "Active authored projects only, hidden worktrees/build outputs excluded", + "freshRestoreOrTestsRun": false, + "projects": [ + { + "name": "Theme", + "repoRoot": "/Users/dohertj2/Desktop/scadaproj", + "testProject": "ZB.MOM.WW.Theme/tests/ZB.MOM.WW.Theme.Tests/ZB.MOM.WW.Theme.Tests.csproj", + "versionFile": "ZB.MOM.WW.Theme/Directory.Packages.props", + "declaredBunit": "2.7.2", + "parserDeclarationOrContext": "1.5.0", + "runnerToPreserve": "xunit 2.9.3", + "targetBunit": "2.7.2", + "cachedAssetsNotFreshRestore": [ + "AngleSharp/1.5.0", + "AngleSharp.Css/1.0.0-beta.157", + "AngleSharp.Diffing/1.1.1", + "bunit/2.7.2" + ], + "implementationStatus": "planned" + }, + { + "name": "Secrets UI", + "repoRoot": "/Users/dohertj2/Desktop/scadaproj", + "testProject": "ZB.MOM.WW.Secrets/tests/ZB.MOM.WW.Secrets.Ui.Tests/ZB.MOM.WW.Secrets.Ui.Tests.csproj", + "versionFile": "ZB.MOM.WW.Secrets/Directory.Packages.props", + "declaredBunit": "1.40.0", + "parserDeclarationOrContext": "1.5.0 central declaration not directly referenced", + "runnerToPreserve": "xunit 2.9.3", + "targetBunit": "2.7.2", + "cachedAssetsNotFreshRestore": [ + "AngleSharp/1.2.0", + "AngleSharp.Css/1.0.0-beta.154", + "AngleSharp.Diffing/1.0.0", + "bunit/1.40.0" + ], + "implementationStatus": "planned" + }, + { + "name": "Overview", + "repoRoot": "/Users/dohertj2/Desktop/scadaproj", + "testProject": "ZB.MOM.WW.Overview/tests/ZB.MOM.WW.Overview.Tests/ZB.MOM.WW.Overview.Tests.csproj", + "versionFile": "ZB.MOM.WW.Overview/tests/ZB.MOM.WW.Overview.Tests/ZB.MOM.WW.Overview.Tests.csproj", + "declaredBunit": "1.40.0", + "parserDeclarationOrContext": "1.5.2", + "runnerToPreserve": "xunit 2.9.3", + "targetBunit": "2.7.2", + "cachedAssetsNotFreshRestore": [ + "AngleSharp/1.5.2", + "AngleSharp.Css/1.0.0-beta.154", + "AngleSharp.Diffing/1.0.0", + "bunit/1.40.0" + ], + "implementationStatus": "planned" + }, + { + "name": "ScadaBridge", + "repoRoot": "/Users/dohertj2/Desktop/ScadaBridge", + "testProject": "tests/ZB.MOM.WW.ScadaBridge.CentralUI.Tests/ZB.MOM.WW.ScadaBridge.CentralUI.Tests.csproj", + "versionFile": "Directory.Packages.props", + "declaredBunit": "2.7.2", + "parserDeclarationOrContext": "1.4.0 cached transitive, scoped suppression", + "runnerToPreserve": "xunit 2.9.3", + "targetBunit": "2.7.2", + "cachedAssetsNotFreshRestore": [ + "AngleSharp/1.4.0", + "AngleSharp.Css/1.0.0-beta.157", + "AngleSharp.Diffing/1.1.1", + "bunit/2.7.2" + ], + "implementationStatus": "planned" + }, + { + "name": "OtOpcUa", + "repoRoot": "/Users/dohertj2/Desktop/OtOpcUa", + "testProject": "tests/Server/ZB.MOM.WW.OtOpcUa.AdminUI.Tests/ZB.MOM.WW.OtOpcUa.AdminUI.Tests.csproj", + "versionFile": "Directory.Packages.props", + "declaredBunit": "2.0.33-preview", + "parserDeclarationOrContext": "1.1.1 cached transitive, scoped suppression", + "runnerToPreserve": "xunit.v3 3.2.2", + "targetBunit": "2.7.2", + "cachedAssetsNotFreshRestore": [ + "AngleSharp/1.1.1", + "AngleSharp.Css/1.0.0-beta.139", + "AngleSharp.Diffing/0.18.2", + "bunit/2.0.33-preview" + ], + "implementationStatus": "planned" + }, + { + "name": "HistorianGateway", + "repoRoot": "/Users/dohertj2/Desktop/HistorianGateway", + "testProject": "tests/ZB.MOM.WW.HistorianGateway.Tests/ZB.MOM.WW.HistorianGateway.Tests.csproj", + "versionFile": "tests/ZB.MOM.WW.HistorianGateway.Tests/ZB.MOM.WW.HistorianGateway.Tests.csproj", + "declaredBunit": "1.40.0", + "parserDeclarationOrContext": "1.5.2", + "runnerToPreserve": "xunit 2.9.3", + "targetBunit": "2.7.2", + "cachedAssetsNotFreshRestore": [ + "AngleSharp/1.5.2", + "AngleSharp.Css/1.0.0-beta.154", + "AngleSharp.Diffing/1.0.0", + "bunit/1.40.0" + ], + "implementationStatus": "planned" + }, + { + "name": "BTDB", + "repoRoot": "/Users/dohertj2/Desktop/BTDB", + "testProject": "tests/ZB.MOM.WW.BTDB.Manager.Tests/ZB.MOM.WW.BTDB.Manager.Tests.csproj", + "versionFile": "tests/ZB.MOM.WW.BTDB.Manager.Tests/ZB.MOM.WW.BTDB.Manager.Tests.csproj", + "declaredBunit": "1.40.0", + "parserDeclarationOrContext": "1.5.2", + "runnerToPreserve": "xunit 2.9.3", + "targetBunit": "2.7.2", + "cachedAssetsNotFreshRestore": [ + "AngleSharp/1.5.2", + "AngleSharp.Css/1.0.0-beta.154", + "AngleSharp.Diffing/1.0.0", + "bunit/1.40.0" + ], + "implementationStatus": "planned" + } + ], + "nonBunitRuntimes": [ + "MxAccessGateway HtmlRenderer", + "ignitionoee router renderer", + "ignitionoee registry Playwright", + "Perspective native runtime" + ], + "cachedPackageEvidence": { + "path": "/Users/dohertj2/.nuget/packages/bunit/2.7.2/bunit.nuspec", + "declaredNet10DependencyMinimums": { + "AngleSharp": "1.4.0", + "AngleSharp.Css": "1.0.0-beta.157", + "AngleSharp.Diffing": "1.1.1" + }, + "note": "Inspect exact restored package again during execution; minima do not establish patched parser runtime compatibility." + } +} diff --git a/docs/plans/2026-11-12-scada-ui-consistency/ignitionoee.md b/docs/plans/2026-11-12-scada-ui-consistency/ignitionoee.md new file mode 100644 index 0000000..02fd124 --- /dev/null +++ b/docs/plans/2026-11-12-scada-ui-consistency/ignitionoee.md @@ -0,0 +1,580 @@ +# ignitionoee UI consistency Implementation Plan + +> **For Codex:** REQUIRED SUB-SKILL: Use `executeplan` to implement this plan task-by-task. + +**Goal:** Converge router, registry and native Perspective UI behavior and visual tokens while preserving their separate runtimes, roles and operational truth. + +**Architecture:** The router adopts the verified Theme package; the independent public-feed registry imports the versioned canonical static asset export without private NuGet prerequisites. Perspective maps exported semantic tokens to native view styles, with no Blazor package or admin-rail requirement on operator panels. + +**Tech Stack:** Router/registry .NET 10 Blazor + xUnit, registry Playwright 1.58.0, Ignition 8.3+ Perspective/Jython 2.7, CPython offline tests and vendored view schemas. + +--- + +## 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. + +## Execution contract + +- Repository: `/Users/dohertj2/Desktop/ignitionoee`. All source/test paths below are relative to that root; use it as cwd unless a step states otherwise. +- Planning date: 2026-11-12. This chapter specifies future work; no implementation or test execution is claimed. +- Read the corresponding `/Users/dohertj2/Desktop/scadaproj/impeccable/ignitionoee.md`, the shared design-system report, the master plan and applicable `AGENTS.md` before execution. +- Reuse a suitable checkout; inspect `git status --short` and preserve user edits. No new worktree, commit, push, package publication or deployment is performed by authoring this plan. +- **Dependency gate:** complete shared Theme G1 compatibility audit, assign `THEME_VERSION`, and verify its artifact before consumer migration. `THEME_VERSION` is a placeholder, never a literal package version to publish. +- Shared G1 supplies semantic status ink (`--ok-ink:#236f34`, `--warn-ink:#855000`, `--bad-ink:#b42121`, `--idle-ink:#535d66`), `--ink-faint:#626970`, and independent blue `--info-ink`; product accent never recolors semantic informational notices. +- G1 adds `TechField.For`, `HintId`, `ErrorId`; callers supply input IDs, `aria-describedby` and `aria-invalid`. G1 adds `ThemeShell.AccentDeep`, `AccentTint`, `AccentBorder`, `AccentFocus` while preserving `Accent`. +- Shared accent aliases must resolve in shell scope: G1 uses `--accent-tint` directly or rebinds inherited aliases at `.app-shell`. Bootstrap `.btn-primary`/ghost component variables must follow shell accent for normal/hover/active/disabled states. Compare computed states before deleting any consumer override. +- G1 also supplies shared focus/busy/reduced-motion and filter/table/dialog recipes. `TechButton.BusyText` is optional; busy adds `aria-busy`. Caller-owned status/alert text announces outcomes, never secret values or every polling update. +- Pilot native dialogs in two consumers before extracting a common dialog component. Do not build a new component package during a first consumer migration. +- Restore/build first and record actual dependency/runtime failures. Complete GB bUnit/parser standardization first. Preserve xUnit, test SDK and Playwright versions unless a specific demonstrated compatibility fix is recorded in GB; do not perform later incidental framework upgrades. Never treat a skipped native/SQL/COM/live test as a pass. +- Each numbered step is one short action. When a step discovers broader product behavior, stop that task at its boundary and update this written plan before expanding implementation scope. + +## Current source and hard boundaries + +- Read `/Users/dohertj2/Desktop/ignitionoee/AGENTS.md`, relevant `CLAUDE.md` sections, `router/README.md`, `registry/README.md`, and `docs/reference/ignition-8.3-resource-format.md`. +- Router central package pin: `router/Directory.Packages.props:85` Theme 0.5.0; Secrets.Ui 0.6.2. Update after G1 dependency audit; preserve shared Secrets compatibility through `SECRETS_UI_VERSION`. +- Registry has no Theme package. `registry/README.md` explicitly keeps private router packages out of its prerequisites. **Decision:** consume verified canonical static exports; do not introduce a private feed or import router authentication/package configuration as a styling shortcut. +- Router tests use xUnit and the existing `PageRenderTest` static renderer, not bUnit. Registry BrowserTests already have Playwright and disposable hosts/SQLite fixture data with cleanup. Reuse them without upgrades. +- Router EF InMemory tests establish semantic behavior, not SQL Server translation/enforcement. Retain `UiSqlTranslationTests` whenever a query/deep-link task touches EF predicates. +- Perspective browser UI is native Ignition; keep Jython 2.7 event code, current tag paths, named query contracts, roles and source-of-count semantics intact. JSON `defaultSize` is design-time metadata, not proof of runtime responsiveness. +- Protected CR history and gateway heartbeat/forwarding rules in AGENTS.md remain untouched. No rebuild, re-forward, backfill, schema migration, PLC write, live driver action or downtime reclassification is part of styling validation. + +## Findings coverage + +| Report finding | Planned task | Runtime | +| --- | --- | --- | +| OEE-01 click-only Jobs rows | OEE-01 | Router | +| OEE-02 unmanaged TechModal | OEE-02 | Router, using registry reference | +| OEE-03 copied registry theme | OEE-03 | Registry static asset import | +| OEE-04 Perspective token drift | OEE-04 | Native views | +| OEE-05 long nav footer visibility | OEE-05 | Router shared shell | +| OEE-06 scheduling context switches | OEE-06 | Router | +| OEE-07 issue recovery consistency | OEE-07 | Router | +| OEE-08 responsive toolbar/table reuse | OEE-08 | Router | +| OEE-09 eligibility vs runtime health | OEE-09 | Registry | +| OEE-10 operator touch density | OEE-10 | Native views | + +## Package/export gate and baseline + +1. From repo root run `dotnet restore router/ZB.MOM.Oee.slnx`; save `dotnet list router/src/ZB.MOM.Oee.Host/ZB.MOM.Oee.Host.csproj package --include-transitive` to the validation record. +2. After G1 audit assigns `THEME_VERSION`, update the central router pin, restore and prove the resolved graph includes its expected shared Theme/Secrets assets. +3. Use Theme TH-08 export `technical-light-web-assets..zip`; require its sourceTag, sourceRevision, sourcePackageSha256, version, per-file SHA256 and semantic token manifest. Verify the immutable artifact before importing into registry or generating native mappings. +4. Run `dotnet test router/tests/ZB.MOM.Oee.Ui.Tests/ZB.MOM.Oee.Ui.Tests.csproj` as baseline. Record infrastructure failures and keep them distinct from design assertions. +5. Run `dotnet build registry/ZB.MOM.MachineRegistry.slnx`, then `dotnet test registry/tests/Registry.BrowserTests --filter FullyQualifiedName~RegistryShellTests` after installing the pinned browser if needed. +6. Browser setup when required: `dotnet build registry/tests/Registry.BrowserTests`; `pwsh registry/tests/Registry.BrowserTests/bin/Debug/net10.0/playwright.ps1 install chromium`. No silent browser version substitution. If PowerShell/browser install is unavailable, report the unmet browser gate. +7. Add `docs/ui-validation/technical-light-family.md` to record fixture endpoints, process stop methods, screenshots and actual state/keyboard results. Keep real credentials and operator databases out of fixtures. + +## OEE-01: Give Jobs details a semantic keyboard disclosure + +**Files:** + +- Modify `router/src/ZB.MOM.Oee.Ui/Components/Pages/Jobs.razor` +- Modify `router/src/ZB.MOM.Oee.Ui/Components/Pages/Jobs.razor.cs` +- Create `router/tests/ZB.MOM.Oee.Ui.Tests/JobsRowDisclosureTests.cs` +- Reuse `router/tests/ZB.MOM.Oee.Ui.Tests/PageRenderTest.cs` + +**Step 1 — Establish the failing behavior.** Create the xUnit class with imports for Jobs, entities and PageRenderTest. Seed a current completed job so the page default date range includes it. The test below guards the actual emitted button semantics, not CSS structure. + +```csharp +[Fact] +public async Task Job_rows_emit_named_details_buttons() +{ + var id = Guid.Parse("11111111-2222-3333-4444-555555555555"); + var html = await PageRenderTest.RenderAsync(db => { + var cell = PageRenderTest.AddHierarchy(db); + var now = DateTime.UtcNow; + db.Jobs.Add(new Job { JobId = id, CellId = cell.CellId, + SourceName = "Operator", Status = JobStatuses.Completed, + JobStepNumber = "0100", StartTime = now.AddMinutes(-10), + EndTime = now, CreatedAt = now }); + }); + Assert.Contains("Details for job", html); + Assert.Contains("aria-expanded=", html); + Assert.DoesNotContain("( + parameters: ParameterView.FromDictionary(new Dictionary { + ["Visible"] = true, ["Title"] = "Review machine mapping" + })); + Assert.Contains(" RenderAsync( + Action? seed = null, + Action? configure = null, + ParameterView? parameters = null) + where T : IComponent +``` + +Keep the existing body/fixtures unchanged except replace `renderer.BeginRenderingComponent(typeof(T), ParameterView.Empty)` with `renderer.BeginRenderingComponent(typeof(T), parameters ?? ParameterView.Empty)`. Current `Microsoft.AspNetCore.Components` imports already supply ParameterView; existing callers keep their default behavior. + +### Actual browser focus acceptance for OEE-02 + +Run this in the existing browser automation session against an isolated router page with an editor account, a machine fixture and no real writes. `page` is the connected Playwright page; supply the actual accessible trigger name from that page. This is executable browser validation code, not an xUnit/static renderer assertion: + +```javascript +const trigger = page.getByRole('button', { name: 'Add machine or line', exact: true }); +await trigger.focus(); +await trigger.press('Enter'); +const dialog = page.getByRole('dialog'); +await dialog.waitFor({ state: 'visible' }); +if (!(await dialog.evaluate(d => d.contains(document.activeElement)))) + throw new Error('Initial focus is outside dialog'); +for (let i = 0; i < 30; i++) { + await page.keyboard.press('Tab'); + if (!(await dialog.evaluate(d => d.contains(document.activeElement)))) + throw new Error('Tab escaped modal'); +} +await page.keyboard.press('Escape'); +await dialog.waitFor({ state: 'hidden' }); +if (!(await trigger.evaluate(e => e === document.activeElement))) + throw new Error('Trigger focus was not restored'); +``` + +Use the exact accessible name found in the fixture; if the name is not “Add machine or line”, update the recorded selector to the real control without weakening the focus assertions. Add Shift+Tab, cancel-button and delayed-busy variants in the same browser pass. Stop fixture processes after validation. + +## OEE-03: Import canonical static assets without a private registry feed + +**Files:** + +- Modify `registry/src/Registry.Host/Components/App.razor` +- Modify `registry/src/Registry.Host/wwwroot/app.css` +- Create `registry/src/Registry.Host/wwwroot/shared-theme/css/theme.css` +- Create `registry/src/Registry.Host/wwwroot/shared-theme/css/layout.css` +- Create `registry/src/Registry.Host/wwwroot/shared-theme/fonts/ibm-plex-sans-400.woff2` +- Create `registry/src/Registry.Host/wwwroot/shared-theme/fonts/ibm-plex-sans-600.woff2` +- Create `registry/src/Registry.Host/wwwroot/shared-theme/fonts/ibm-plex-mono-500.woff2` +- Create `registry/src/Registry.Host/wwwroot/shared-theme/tokens.json` +- Create `registry/src/Registry.Host/wwwroot/shared-theme/manifest.json` +- Create `deploy/scripts/import-technical-light-assets.py` +- Create `tests/test_technical_light_asset_import.py` +- Create `docs/design/technical-light/registry-asset-import.json` +- Modify `registry/tests/Registry.BrowserTests/RegistryShellTests.cs` + +**Step 1 — Establish the failing behavior.** Capture current registry pages on a disposable seeded database; assert the intended imported CSS/fonts URLs will return 200 and the browser uses Plex with shared semantic ink. Before import these URLs are absent. This is a visual/static-asset migration, not a reason to add mirrored CSS unit tests. + +**Step 2 — Run the focused check.** From the repository root: + +```bash +dotnet build registry/ZB.MOM.MachineRegistry.slnx +dotnet test registry/tests/Registry.BrowserTests/Registry.BrowserTests.csproj --filter FullyQualifiedName~RegistryShellTests +``` + +Expected before: the new shared-theme asset requests are absent before import; current copied palette/font rules remain. + +**Step 3 — Implement in small edits.** + +1. Verify TH-08 zip manifest version/sourceTag/sourceRevision/sourcePackageSha256 and every file SHA256; reject path traversal, missing files and unexpected versions in the importer before writing. +2. Expose importer CLI `--artifact ZIP --destination DIRECTORY --expected-version VERSION --check` and require manifest validation before writing; omit `--check` only for the intentional import after a verified dry run. Extract only documented css/, fonts/, tokens.json and manifest.json under wwwroot/shared-theme; save artifact checksum/import provenance in docs/design/technical-light/registry-asset-import.json. +3. Load shared-theme/css/theme.css then layout.css before registry app/domain sheets. Verify relative ../fonts URLs; do not load a second Plex declaration afterward. +4. Remove duplicate :root palette/font/base rules from app.css only after comparing computed declarations. Registry currently uses shell/side-rail/main/button/table selectors; preserve necessary registry chassis geometry and local dialog/floorplan/evidence selectors until explicitly migrated. +5. Map local --hover/--active aliases to canonical --hover-bg/--active-bg where necessary. Use semantic --*-ink for text and independent blue --info-ink. Keep eligibility meaning local. +6. Update RegistryShellTests with asset-load/contrast/overflow assertions in the existing disposable process harness. Do not change public NuGet feeds or startup permissions. + +**Step 4 — Verify the change.** Add/run `python3 -m unittest discover -s tests -p test_technical_light_asset_import.py -v` for manifest/hash rejection, archive path escape rejection, check-mode non-mutation and successful verified import. Re-run Step 2; expected after: PASS for the named tests or all stated visual checks. Run registry Inventory, Machines, Drivers/editor, Identity, Verification and Floorplans at all specified sizes. Preserve keyboard map alternatives and 200% zoom. Verify one active nav item, no font 404s, native editor focus, existing button geometry and no document overflow. Keep current domain CSS if a shared generic selector changes its behavior until mapped deliberately. + +**Step 5 — Commit.** Stage only the listed production/test/evidence files, inspect `git diff --cached`, then `git commit -m "style: import canonical Technical-Light registry assets"`. Do not include generated credentials, runtime data or unrelated edits. + +## OEE-04: Map shared tokens into native Perspective views + +**Files:** + +- Modify `projects/OEE_Site/com.inductiveautomation.perspective/views/KpiTile/view.json` +- Modify `projects/OEE_Site/com.inductiveautomation.perspective/views/CellTile/view.json` +- Modify `projects/OEE_Site/com.inductiveautomation.perspective/views/NavHeader/view.json` +- Modify `projects/OEE_Site/com.inductiveautomation.perspective/views/Overview/view.json` +- Modify `projects/OEE_Site/com.inductiveautomation.perspective/views/ReasonPicker/view.json` +- Modify `projects/OEE_Site/com.inductiveautomation.perspective/views/JobEntry/view.json` +- Create `docs/design/technical-light/perspective-token-map.json` +- Create `deploy/scripts/apply-perspective-theme.py` +- Create `docs/ui-validation/perspective-technical-light.md` + +**Step 1 — Establish the failing behavior.** Use a bounded source/visual inventory of literal surface/ink/status colors and compare them with the verified export manifest. The first pass changes style properties only; no new style-class resource format is invented. Test the migration tool dry-run and schema/live acceptance rather than assertions mirroring every color declaration. + +**Step 2 — Run the focused check.** From the repository root: + +```bash +python3 deploy/scripts/apply-perspective-theme.py --check +bash deploy/scripts/ign-deploy.sh validate --all projects/OEE_Site +``` + +Expected before: before tool creation the command is missing; after tool creation but before applying it reports only allowlisted divergent style paths. Validator baseline may already pass and is not evidence of visual conformity. + +**Step 3 — Implement in small edits.** + +1. Consume TH-08 tokens.json and source/hash provenance; define explicit native props.style mappings by view/component path, not arbitrary global string replacement. +2. Implement --check and --apply using Python stdlib; --check does not mutate. Reject attempts to alter events, propConfig bindings, params other than approved density inputs, tag paths or named-query references. +3. Apply paper/card/ink/semantic status/spacing/font mappings to the six exact views listed. Preserve dynamic status expressions; map their values through canonical semantics without converting unavailable to zero. +4. Use existing native props.style initially. The repository has no verified named-style resource example; defer named-style extraction until Designer export establishes its manifest/payload format and this file table is updated. +5. Do not add Theme/Blazor classes, Bootstrap CSS or admin side rail to Perspective. Use the existing native operator navigation and preserve Jython 2.7 event scripts. + +**Step 4 — Verify the change.** Re-run Step 2; expected after: PASS for the named tests or all stated visual checks. Run offline view validation, then import into a disposable Ignition Designer/session using the repository workflow. Check kiosk and handheld rendering, computed contrast, fonts/fallback availability and dynamic state colors. Designer/live resource acceptance is a required gate; offline JSON validation alone is insufficient. + +**Step 5 — Commit.** Stage only the listed production/test/evidence files, inspect `git diff --cached`, then `git commit -m "style: map shared Technical-Light tokens to Perspective views"`. Do not include generated credentials, runtime data or unrelated edits. + +## OEE-05: Keep long router navigation and sign-out reachable + +**Files:** + +- Modify `router/src/ZB.MOM.Oee.Ui/Components/Layout/MainLayout.razor` +- Modify `router/src/ZB.MOM.Oee.Ui/Components/Layout/NavMenu.razor` +- Update `docs/ui-validation/technical-light-family.md` + +**Step 1 — Establish the failing behavior.** At 1024×768 and 200% zoom, expand all authorized nav sections and record whether footer/sign-out are visible/reachable. Do not add a test that only searches source for ScrollNav. + +**Step 2 — Run the focused check.** From the repository root: + +```bash +dotnet build router/src/ZB.MOM.Oee.Host/ZB.MOM.Oee.Host.csproj +``` + +Expected before: the current layout does not opt into scroll nav; the full expanded rail can push footer beyond the viewport. + +**Step 3 — Implement in small edits.** + +1. After THEME_VERSION gate, opt into ThemeShell ScrollNav=true. +2. Keep nav keys and policy gates unchanged. If changing initial group expansion, preserve stored state and never hide current destination. +3. Supply correctly bounded page/nav heights through G1 only; do not reintroduce local height:100vh wrappers that fight shared mobile-shell behavior. + +**Step 4 — Verify the change.** Re-run Step 2; expected after: PASS for the named tests or all stated visual checks. Keyboard-reach every permitted nav item and Sign out at 1024×768 and zoom; compare mobile collapsed/open content remains visible. Confirm no double-scrolling trap or footer overlap and Viewer/Admin nav differences remain correct. + +**Step 5 — Commit.** Stage only the listed production/test/evidence files, inspect `git diff --cached`, then `git commit -m "style: keep router navigation footer reachable"`. Do not include generated credentials, runtime data or unrelated edits. + +## OEE-06: Preserve scope across related scheduling screens + +**Files:** + +- Modify `router/src/ZB.MOM.Oee.Ui/Components/Pages/Schedules.razor` +- Modify `router/src/ZB.MOM.Oee.Ui/Components/Pages/ScheduleAssignments.razor` +- Modify `router/src/ZB.MOM.Oee.Ui/Components/Pages/ScheduleAssignments.razor.cs` +- Modify `router/src/ZB.MOM.Oee.Ui/Components/Pages/ScheduleCalendar.razor` +- Modify `router/src/ZB.MOM.Oee.Ui/Components/Pages/ScheduleCalendar.razor.cs` +- Modify `router/src/ZB.MOM.Oee.Ui/Components/Pages/SchedulePreview.razor` +- Modify `router/src/ZB.MOM.Oee.Ui/Components/Pages/SchedulePreview.razor.cs` +- Modify `router/src/ZB.MOM.Oee.Ui/Components/Pages/ScheduleEditor.razor` +- Modify `router/src/ZB.MOM.Oee.Ui/Components/Pages/ScheduleEditor.razor.cs` +- Create `router/src/ZB.MOM.Oee.Ui/Logic/ScheduleScopeLinks.cs` +- Create `router/tests/ZB.MOM.Oee.Ui.Tests/ScheduleScopeLinksTests.cs` + +**Step 1 — Establish the failing behavior.** Create a small pure link builder with named schedule/cell/site inputs and tests for encoding, missing optional scope and route names. This is navigation context, not a new schedule state store. + +```csharp +[Fact] +public void Preview_link_preserves_cell_scope_and_encodes_site_code() +{ + var href = ScheduleScopeLinks.Preview(cellId: 104, siteCode: "A&B"); + Assert.StartsWith("/schedule-preview?", href); + Assert.Contains("cellId=104", href); + Assert.Contains("site=A%26B", href); +} +[Fact] +public void Preview_without_scope_has_no_fabricated_selection() +{ + Assert.Equal("/schedule-preview", ScheduleScopeLinks.Preview(null, null)); +} +``` + +**Step 2 — Run the focused check.** From the repository root: + +```bash +dotnet test router/tests/ZB.MOM.Oee.Ui.Tests/ZB.MOM.Oee.Ui.Tests.csproj --filter FullyQualifiedName~ScheduleScopeLinksTests +``` + +Expected before: ScheduleScopeLinks does not exist; initially compilation fails, then behavioral expectations fail until implemented. + +**Step 3 — Implement in small edits.** + +1. Current SchedulePreview/Calendar keep private selected IDs and expose no query hydration; ScheduleEditor has the route ScheduleId. Introduce a documented additive navigation contract: `cellId` is the selected cell ID, `site` is an optional encoded site code, and the editor retains its route ScheduleId. Resolve cell ancestors from validated loaded data and reject mismatching supplied site/cell context. Reuse existing query names if a later source audit finds they have been added; update the helper tests together before implementation. +2. Build related-task links carrying applicable selected schedule/cell/site via query parameters. Treat them as related pages, not mandatory linear wizard steps. +3. Hydrate only valid supplied context with server-validated IDs/codes; display absent/retired/denied scope clearly and keep existing selection fallback. +4. Keep all schedule write guards, effective-time and denominator logic unchanged; read-only preview must not submit a schedule mutation. + +**Step 4 — Verify the change.** Re-run Step 2; expected after: PASS for the named tests or all stated visual checks. Select one cell/schedule, visit assignments → calendar → preview and verify scope persists and denominator explanation links to the correct source/override. Check deep-link refresh, missing/retired scope and denied Editor action. Run ScheduleWriteGuardTests and existing schedule tests. + +**Step 5 — Commit.** Stage only the listed production/test/evidence files, inspect `git diff --cached`, then `git commit -m "feat: retain scheduling context across related pages"`. Do not include generated credentials, runtime data or unrelated edits. + +## OEE-07: Standardize issue-state feedback without hiding consequences + +**Files:** + +- Modify `router/src/ZB.MOM.Oee.Ui/Components/Pages/ConfigIssues.razor` +- Modify `router/src/ZB.MOM.Oee.Ui/Components/Pages/ConfigIssues.razor.cs` +- Modify `router/src/ZB.MOM.Oee.Ui/Components/Pages/EnrichmentIssues.razor` +- Create `router/tests/ZB.MOM.Oee.Ui.Tests/ConfigIssuesFeedbackTests.cs` +- Modify `router/tests/ZB.MOM.Oee.Ui.Tests/EnrichmentIssueBuilderTests.cs` + +**Step 1 — Establish the failing behavior.** Render ConfigIssues using existing PageRenderTest with an empty source and with a failing IDbContextFactory registration. Assert no-issues success differs from evaluation failure and that failure text is safe/recoverable. Add a sequential success/failure browser fixture for retained stale results. + +**Step 2 — Run the focused check.** From the repository root: + +```bash +dotnet test router/tests/ZB.MOM.Oee.Ui.Tests/ZB.MOM.Oee.Ui.Tests.csproj --filter FullyQualifiedName~ConfigIssuesFeedbackTests +``` + +Expected before: the current failed-load notice includes raw error text and has no consistent stale/retry summary. + +**Step 3 — Implement in small edits.** + +1. Keep evaluated timestamp/count beside page heading; introduce explicit never-loaded/loading/loaded/refresh-failed state. +2. On refresh failure retain previous result set marked stale, and expose Retry; first-load failure cannot say no issues. +3. Use safe user summary with expandable sanitized technical detail; remove raw exception text from primary notice without suppressing server diagnostics. +4. Preserve severity, affected scope, consequence and exact fixing link; align enrichment feedback to the same state/notice contract. +5. Announce one caller-owned result summary after user re-evaluation, not individual rows or every polling tick. + +**Step 4 — Verify the change.** Re-run Step 2; expected after: PASS for the named tests or all stated visual checks. Exercise no issues, one error, capped/large queue, denied fix target, DB failure then recovery and late completion after navigation. Confirm existing whole-Guid Jobs links remain correct and no exception leaks credentials/connection strings. + +**Step 5 — Commit.** Stage only the listed production/test/evidence files, inspect `git diff --cached`, then `git commit -m "fix: unify router issue queue recovery states"`. Do not include generated credentials, runtime data or unrelated edits. + +## OEE-08: Reuse wrapping toolbar/table contracts across router + +**Files:** + +- Modify `router/src/ZB.MOM.Oee.Ui/Components/Pages/Oee.razor` +- Modify `router/src/ZB.MOM.Oee.Ui/Components/Pages/Jobs.razor` +- Modify `router/src/ZB.MOM.Oee.Ui/Components/Pages/SchedulePreview.razor` +- Modify `router/src/ZB.MOM.Oee.Ui/Components/Pages/Rates/RatePreview.razor` +- Modify `router/src/ZB.MOM.Oee.Ui/Components/Pages/Rates/RateCoverage.razor` +- Update `docs/ui-validation/technical-light-family.md` + +**Step 1 — Establish the failing behavior.** Capture the already-repaired OEE toolbar as a reference, plus Jobs/schedule/rate screens at 390px and zoom. This is responsive composition: verify actual bounding boxes/overflow rather than copying styles into assertion strings. + +**Step 2 — Run the focused check.** From the repository root: + +```bash +dotnet build router/src/ZB.MOM.Oee.Host/ZB.MOM.Oee.Host.csproj +dotnet test router/tests/ZB.MOM.Oee.Ui.Tests/ZB.MOM.Oee.Ui.Tests.csproj --filter FullyQualifiedName~UiSqlTranslationTests +``` + +Expected before: OEE has a local container query while related toolbars need separate measured comparison; record any baseline overflow instead of assuming it. + +**Step 3 — Implement in small edits.** + +1. Use G1 wrapping filter utility where it matches the existing OEE fix; remove only the superseded page-local query. +2. Keep controls labeled and dates/scopes visible when wrapped; apply coarse-pointer density through shared recipe. +3. Contain wide tables in named focusable scrolling regions; keep critical identifiers and explicit details controls reachable. +4. Preserve OEE fact-window cap, unknown-value handling, aggregation, missing-row semantics and SQL queries exactly. + +**Step 4 — Verify the change.** Re-run Step 2; expected after: PASS for the named tests or all stated visual checks. Verify desktop/mobile/zoom/coarse-pointer states and actual document width. Recheck OEE count integrity and scope totals using existing tests; no layout-only unit tests. At most one batched visual correction pass after the initial comparison. + +**Step 5 — Commit.** Stage only the listed production/test/evidence files, inspect `git diff --cached`, then `git commit -m "style: reuse responsive router filter and table patterns"`. Do not include generated credentials, runtime data or unrelated edits. + +## OEE-09: Keep eligibility and verification semantics distinct from health + +**Files:** + +- Modify `registry/src/Registry.Host/Components/Pages/Drivers.razor` +- Modify `registry/src/Registry.Host/wwwroot/app.css` +- Modify `registry/tests/Registry.BrowserTests/RegistryWorkflowsTests.cs` +- Modify `registry/tests/Registry.BrowserTests/RegistryOperationsTests.cs` + +**Step 1 — Establish the failing behavior.** The current catalog already states the correct eligibility meaning. Add preservation assertions in an existing disposable browser workflow; this is a regression guard around the asset migration, so it can legitimately pass before styling. Do not manufacture a failing behavior when the semantic behavior already exists. + +```csharp +// Insert in the existing async browser workflow after its fixture starts: +await page.GotoAsync(url + "/drivers"); +await Assertions.Expect(page.GetByRole(AriaRole.Heading, + new() { Name = "Driver catalog", Exact = true })).ToBeVisibleAsync(); +await Assertions.Expect(page.GetByText( + "Production eligibility permits selection for a mapping. It does not deploy or commission a driver.", + new() { Exact = true })).ToBeVisibleAsync(); +Assert.Equal(0, await page.Locator(".driver-status") + .Filter(new() { HasText = "Healthy" }).CountAsync()); +``` + +**Step 2 — Run the focused check.** From the repository root: + +```bash +dotnet test registry/tests/Registry.BrowserTests/Registry.BrowserTests.csproj --filter FullyQualifiedName~RegistryWorkflowsTests +``` + +Expected before: the semantic preservation test may pass at baseline; the gate is that it must remain green after OEE-03. Any styling change that replaces eligibility with Healthy must fail it. + +**Step 3 — Implement in small edits.** + +1. Keep Eligible/Not eligible labels and copy explaining mapping selection rather than deployment/commissioning. +2. Map the local eligibility/status class to appropriate shared semantic ink without renaming it to runtime health. +3. Retain prerequisites, evidence, revisions, change reason and concurrency reload in the existing native editor. +4. Preserve the floorplan keyboard location list and evidence distinctions under the same asset migration; no new operational-state inference from catalog records. + +**Step 4 — Verify the change.** Re-run Step 2; expected after: PASS for the named tests or all stated visual checks. Use existing Playwright seeded registry harness and insert assertions immediately after navigating to /drivers. Open a driver, test field validation, cancel/return focus and revision conflict, then compare current mobile editor layout. + +**Step 5 — Commit.** Stage only the listed production/test/evidence files, inspect `git diff --cached`, then `git commit -m "test: preserve registry eligibility meaning during theme adoption"`. Do not include generated credentials, runtime data or unrelated edits. + +## OEE-10: Propagate operator touch density through reason entry + +**Files:** + +- Modify `projects/OEE_Site/com.inductiveautomation.perspective/views/ReasonPicker/view.json` +- Modify `projects/OEE_Site/com.inductiveautomation.perspective/views/JobEntry/view.json` +- Modify `projects/OEE_Site/com.inductiveautomation.perspective/views/PanelCell/view.json` +- Modify `projects/OEE_Site/com.inductiveautomation.perspective/views/CellDetail/view.json` +- Modify `projects/OEE_Site/com.inductiveautomation.perspective/views/NavHeader/view.json` +- Create `tests/test_operator_touch_context.py` +- Update `docs/ui-validation/perspective-technical-light.md` + +**Step 1 — Establish the failing behavior.** Add a CPython unittest for the cross-view touch-context contract, not exact CSS values. ReasonPicker must accept an input touch flag and the native caller must explicitly pass it without changing downtime event routing. Use existing JSON walkers from test_cell_detail_view.py; do not add a new test framework. + +**Step 2 — Run the focused check.** From the repository root: + +```bash +python3 -m unittest discover -s tests -p test_operator_touch_context.py -v +bash deploy/scripts/ign-deploy.sh validate --all projects/OEE_Site +``` + +Expected before: ReasonPicker currently has no touch input contract, so the focused assertion fails before implementation. + +**Step 3 — Implement in small edits.** + +1. Add a native input touch parameter with false default and proper propConfig; propagate existing caller touch context into ReasonPicker popups/embeds. +2. Keep JobEntry touch behavior (already uses 64px controls) at least as usable; do not shrink working operator targets merely to match compact desktop admin rows. +3. Apply G1 density mapping to dropdown/comment/save/cancel fields while keeping cell/current-job/stop-time context visible. +4. Preserve role check and basePath/eventId/eventStart/mode/popupId contracts, reclassification behavior and close-only-on-clean-save event logic. +5. Keep unavailable/unknown KPI values explicit and ensure top navigation remains usable on kiosk/handheld; do not replace process-panel bindings or introduce PLC actions. + +**Step 4 — Verify the change.** Re-run Step 2; expected after: PASS for the named tests or all stated visual checks. Validate offline schemas and existing cell-count/manual-entry/downtime tests, then use disposable Ignition sessions at 1024/1280px panel and 390px handheld. Test live and reclassify modes, touch true/false, unavailable tag value, denied role and failed save (popup remains with readable feedback). No real downtime reclassification is required. + +**Step 5 — Commit.** Stage only the listed production/test/evidence files, inspect `git diff --cached`, then `git commit -m "style: carry operator touch context into reason entry"`. Do not include generated credentials, runtime data or unrelated edits. + +### OEE-10 failing native-context test + +Create `tests/test_operator_touch_context.py` with Python 3 stdlib only. This checks whether callers can select the intended density variant; it does not assert particular CSS numbers or claim to emulate Ignition rendering. + +```python +import json +import pathlib +import unittest + +ROOT = pathlib.Path(__file__).resolve().parents[1] +VIEWS = ROOT / "projects/OEE_Site/com.inductiveautomation.perspective/views" + +class OperatorTouchContextTests(unittest.TestCase): + def test_reason_picker_accepts_explicit_touch_input(self): + view = json.loads((VIEWS / "ReasonPicker/view.json").read_text()) + self.assertIs(view["params"]["touch"], False) + self.assertEqual("input", view["propConfig"]["params.touch"]["paramDirection"]) + +if __name__ == "__main__": + unittest.main() +``` + +Add a second test that walks the actual caller event/embedded-view payload and checks `touch` is supplied, after inspecting its current native component path. Preserve behavioral script tests from the existing repository instead of asserting string equality for all Jython event code. + +## Cross-cutting state and viewport matrix + +| State | Expected contract | Verification | +| --- | --- | --- | +| First load / slow work | Page identity remains; busy action disabled with meaningful busy text; no false successful zero | Delayed fixture and keyboard | +| Healthy | Text label plus status token, sampled time, real scope | Representative fixture | +| Warning / failed dependency | Plain summary, affected scope and recovery; safe detail disclosure | Fault fixture; no raw secret/connection string | +| Refresh fails after success | Keep last good data visibly marked stale; retry does not clear context | Sequential success/failure fake | +| Empty / no matches | Different from loading/failure; clear-filter or next action | Empty source and filtered-to-zero separately | +| Unavailable / unknown | Show unknown/n/a, never substitute numeric zero or Healthy | Null/missing fixture | +| Permission denied | Route and action gates remain server-enforced; nav reflects existing policy | Viewer/Admin/denied accounts | +| Long content | Full identifiers available in detail/copy context; table scroll local | 200-character path and error | +| Keyboard / modal | Visible focus; enter/space activation; real modal inertness and focus restoration | Browser test, not HtmlRenderer | +| Narrow / zoom / motion | 1440×900, 1024×768, 390×844, 200% zoom; reduced motion keeps status feedback | Batched visual pass and at most one confirmation pass | + +No runtime timestamps or status values in a mockup are deployment evidence. Keep status domain mapping app-owned. Test color contrast against actual computed backgrounds; screenshots alone do not establish WCAG compliance. + +## Native validation, release and rollback + +### Router + +- After focused tasks, run `dotnet test router/tests/ZB.MOM.Oee.Ui.Tests/ZB.MOM.Oee.Ui.Tests.csproj` and relevant Host/security tests once. Query changes require SqlServer translation tests; no InMemory green result proves a SQL execution plan or production permissions. +- Validate all TechModal caller families, keyboard Jobs details, Viewer/Editor/Admin nav, long rail, mobile shell and shared accent/status states in an isolated router host. +- Record actual package graph and `THEME_VERSION`; retain compatible Secrets.Ui rather than accidentally resolving two Theme generations. + +### Registry + +- Run `dotnet build registry/ZB.MOM.MachineRegistry.slnx`, `dotnet test registry/tests/Registry.BrowserTests`, and `dotnet test registry/tests/Registry.Tests --filter 'Category!=RealInputs'` for synthetic checks on a code-only checkout. +- `Category=RealInputs` requires local migration workbooks and SourceInfo files. Run it only with those inputs supplied and explicitly record if missing; do not claim full suite green after filtering. +- Existing browser harnesses seed their own data directories and terminate their host in finally. Preserve this cleanup; never point them at an operator database, shared SQL server or existing vault. +- Record static export zip/version/source-tag/hash manifest and imported file checksums. Registry remains buildable on its public-feed graph. + +### Perspective + +- Run `bash deploy/scripts/ign-deploy.sh validate --all projects/OEE_Site`, focused new tests, `python3 tests/test_cell_detail_view.py -v`, and existing impacted downtime/manual-entry tests; then one appropriate broader offline run. +- Use the repository deployment tools only for a separately authorized disposable validation gateway, retaining view/schema checks. This plan does not execute deployment. Designer resource acceptance, actual font availability, native input behavior, screen-reader output and panel interaction need live session evidence. +- No `oee.rebuild`, CR history re-forward, DB/UDT schema change, heartbeat network call or real production job/downtime write is required. Preserve protected history periods verbatim. + +### Rollback + +1. Keep separate commits for router package/assets, router interactions, registry import/domain compatibility and native view mappings. +2. Router rollback restores the prior coherent UI/package graph (Theme currently 0.5.0) and its corresponding JS/markup together; validate modal and role behavior. +3. Registry rollback restores the prior app.css/font declarations/App.razor load order and removes only imported generated assets. It must not touch registry DB, revisions, vault or publication journals. +4. Perspective rollback restores prior view resources and associated approved style mapping artifacts together through the existing deployment workflow. Never revert runtime facts, job IDs, reason classifications or tag providers to undo a visual change. +5. Compare final deployed/source commit IDs and rerun the documented read-only smoke paths after any authorized rollout/rollback. Keep live limitations visible in the release record. + +**Done:** all ten findings have evidence-backed implementation/validation paths; shared visual tokens remain canonical while the router, independent registry and operator runtime retain their proper behavior and platform boundaries. diff --git a/docs/plans/2026-11-12-scada-ui-consistency/plan-validation.json b/docs/plans/2026-11-12-scada-ui-consistency/plan-validation.json new file mode 100644 index 0000000..feaf0d1 --- /dev/null +++ b/docs/plans/2026-11-12-scada-ui-consistency/plan-validation.json @@ -0,0 +1,30 @@ +{ + "taskCount": 100, + "coveredRecommendations": 81, + "checkedLocalLinks": 69, + "validationErrors": [], + "implementationExecuted": false, + "checks": [ + "Required headers", + "Unique task IDs", + "Task locations", + "Complete recommendation coverage", + "All mapped tasks exist", + "Local Markdown targets", + "bUnit inventory project/version paths", + "GB dependencies for all UI tasks", + "Post-GB snippets use stable APIs", + "Runner/non-bUnit APIs preserved" + ], + "independentReviewCorrections": [ + "Shell-scoped accent aliases and actual Bootstrap component colors", + "Limited pre-G1 registry candidate pilot avoids release cycle", + "Clean source/version commit before pack/export provenance", + "Secrets UI-only version and actual Abstractions dependency set", + "Approved public/private restore sources preserved" + ], + "chapterCount": 10, + "bunitProjectCount": 7, + "targetBunit": "2.7.2", + "bunitGate": "GB before every Theme/UI task" +} diff --git a/docs/plans/2026-11-12-scada-ui-consistency/source-baselines.json b/docs/plans/2026-11-12-scada-ui-consistency/source-baselines.json new file mode 100644 index 0000000..b04f4ad --- /dev/null +++ b/docs/plans/2026-11-12-scada-ui-consistency/source-baselines.json @@ -0,0 +1,44 @@ +[ + { + "project": "OtOpcUa", + "review_head": "412da27c5fb7e440e4a75d4f8e82e0e5b9832411", + "planning_head": "412da27c5fb7e440e4a75d4f8e82e0e5b9832411", + "changed_since_review": false + }, + { + "project": "MxAccessGateway", + "review_head": "7481b959053cf29b0d89ca3686b24a60668994d2", + "planning_head": "7481b959053cf29b0d89ca3686b24a60668994d2", + "changed_since_review": false + }, + { + "project": "ScadaBridge", + "review_head": "482ac66548a8b3c1e165f06d8e14d68efce4c5aa", + "planning_head": "7e34d7c2d5e86c57bc6ceae2bcaffac176496454", + "changed_since_review": true + }, + { + "project": "HistorianGateway", + "review_head": "fa9cf31a563d3add4c5414b5991ad6b403c755f0", + "planning_head": "fa9cf31a563d3add4c5414b5991ad6b403c755f0", + "changed_since_review": false + }, + { + "project": "ignitionoee", + "review_head": "14780f7a12b68bb9a274eca23c7add10666bd338", + "planning_head": "14780f7a12b68bb9a274eca23c7add10666bd338", + "changed_since_review": false + }, + { + "project": "BTDB", + "review_head": "5b897985ef0756ea592175b02e281decca334bdf", + "planning_head": "5b897985ef0756ea592175b02e281decca334bdf", + "changed_since_review": false + }, + { + "project": "scadaproj", + "review_head": "e6a724ba8e7d7276d4129be6c37ac92887af94b2", + "planning_head": "d93ca7b8c29298ee95fbeface3e40eda13e2a796", + "changed_since_review": true + } +] diff --git a/docs/plans/2026-11-12-scada-ui-consistency/tasks.json b/docs/plans/2026-11-12-scada-ui-consistency/tasks.json new file mode 100644 index 0000000..b05fe92 --- /dev/null +++ b/docs/plans/2026-11-12-scada-ui-consistency/tasks.json @@ -0,0 +1,1902 @@ +{ + "schemaVersion": 1, + "created": "2026-11-12", + "status": "in_progress", + "master": "../2026-11-12-scada-ui-consistency.md", + "executionSkill": "executeplan", + "notes": [ + "Task IDs are separate from finding IDs; use the coverage map, especially Secrets.", + "Expected test results in chapter text are future acceptance criteria, not observed runs.", + "Use G1 candidate exceptions for limited Overview, ScadaBridge and registry pilots; do not require full consumer completion before shared release.", + "All UI tasks require GB; candidate exceptions waive released G1 only and never waive bUnit standardization." + ], + "chapterOrder": [ + "BUnit", + "Theme", + "Secrets", + "Overview", + "ScadaBridge", + "OtOpcUa", + "MxAccessGateway", + "HistorianGateway", + "BTDB", + "ignitionoee" + ], + "taskCount": 100, + "recommendationCount": 81, + "tasks": [ + { + "id": "BU-01", + "title": "Record pre-upgrade tests and package graphs", + "chapter": "BUnit.md", + "line": 61, + "status": "in_progress", + "prerequisiteGates": [ + "G0" + ], + "dependsOnTasks": [], + "requirement": "User request: standardize every existing bUnit project on 2.7.2 before Theme/UI work.", + "remaining": "Fresh isolated baselines for four sister repositories; managed worktree calls still pending." + }, + { + "id": "BU-02", + "title": "Prove the dependency candidate with a minimal render probe", + "chapter": "BUnit.md", + "line": 71, + "status": "completed", + "prerequisiteGates": [ + "G0" + ], + "dependsOnTasks": [ + "BU-01" + ], + "requirement": "User request: standardize every existing bUnit project on 2.7.2 before Theme/UI work.", + "evidence": "components/ui-theme/validation/bunit-2.7.2/probes" + }, + { + "id": "BU-03", + "title": "Verify Theme's existing stable baseline", + "chapter": "BUnit.md", + "line": 151, + "status": "completed", + "prerequisiteGates": [ + "G0" + ], + "dependsOnTasks": [ + "BU-02" + ], + "requirement": "User request: standardize every existing bUnit project on 2.7.2 before Theme/UI work.", + "evidence": "components/ui-theme/validation/bunit-2.7.2/Theme" + }, + { + "id": "BU-04", + "title": "Verify ScadaBridge 2.7.2 and reconcile its parser suppression", + "chapter": "BUnit.md", + "line": 158, + "status": "pending_worktree", + "prerequisiteGates": [ + "G0" + ], + "dependsOnTasks": [ + "BU-02" + ], + "requirement": "User request: standardize every existing bUnit project on 2.7.2 before Theme/UI work.", + "remaining": "No path or operationId returned by create_worktree; original checkout not modified/tested." + }, + { + "id": "BU-05", + "title": "Upgrade Secrets UI tests and enforce its real parser reference", + "chapter": "BUnit.md", + "line": 165, + "status": "completed", + "prerequisiteGates": [ + "G0" + ], + "dependsOnTasks": [ + "BU-02" + ], + "requirement": "User request: standardize every existing bUnit project on 2.7.2 before Theme/UI work.", + "evidence": "components/ui-theme/validation/bunit-2.7.2/Secrets" + }, + { + "id": "BU-06", + "title": "Upgrade Overview tests and preserve timer lifecycle assertions", + "chapter": "BUnit.md", + "line": 172, + "status": "completed", + "prerequisiteGates": [ + "G0" + ], + "dependsOnTasks": [ + "BU-02" + ], + "requirement": "User request: standardize every existing bUnit project on 2.7.2 before Theme/UI work.", + "evidence": "components/ui-theme/validation/bunit-2.7.2/Overview" + }, + { + "id": "BU-07", + "title": "Replace OtOpcUa's preview while preserving xUnit v3 cancellation", + "chapter": "BUnit.md", + "line": 179, + "status": "pending_worktree", + "prerequisiteGates": [ + "G0" + ], + "dependsOnTasks": [ + "BU-02" + ], + "requirement": "User request: standardize every existing bUnit project on 2.7.2 before Theme/UI work.", + "remaining": "No path or operationId returned by create_worktree; original checkout not modified/tested." + }, + { + "id": "BU-08", + "title": "Upgrade HistorianGateway dashboard fixtures", + "chapter": "BUnit.md", + "line": 186, + "status": "pending_worktree", + "prerequisiteGates": [ + "G0" + ], + "dependsOnTasks": [ + "BU-02" + ], + "requirement": "User request: standardize every existing bUnit project on 2.7.2 before Theme/UI work.", + "remaining": "No path or operationId returned by create_worktree; original checkout not modified/tested." + }, + { + "id": "BU-09", + "title": "Upgrade BTDB fixture helpers and navigation/auth doubles", + "chapter": "BUnit.md", + "line": 193, + "status": "pending_worktree", + "prerequisiteGates": [ + "G0" + ], + "dependsOnTasks": [ + "BU-02" + ], + "requirement": "User request: standardize every existing bUnit project on 2.7.2 before Theme/UI work.", + "remaining": "No path or operationId returned by create_worktree; original checkout not modified/tested." + }, + { + "id": "BU-10", + "title": "Verify cross-project consistency and close GB", + "chapter": "BUnit.md", + "line": 200, + "status": "planned", + "prerequisiteGates": [ + "G0" + ], + "dependsOnTasks": [ + "BU-03", + "BU-04", + "BU-05", + "BU-06", + "BU-07", + "BU-08", + "BU-09" + ], + "requirement": "User request: standardize every existing bUnit project on 2.7.2 before Theme/UI work." + }, + { + "id": "TH-01", + "title": "Capture post-GB baseline and Theme compatibility decisions (DS-06)", + "chapter": "Theme.md", + "line": 44, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "TH-02", + "title": "Introduce readable semantic text inks (DS-01)", + "chapter": "Theme.md", + "line": 67, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "TH-03", + "title": "Associate TechField labels and descriptions (DS-02)", + "chapter": "Theme.md", + "line": 137, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "TH-04", + "title": "Carry the whole product accent through interaction states (DS-03)", + "chapter": "Theme.md", + "line": 178, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "TH-05", + "title": "Complete busy feedback without changing disabled semantics (DS-04)", + "chapter": "Theme.md", + "line": 216, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "TH-06", + "title": "Focus, reduced motion and responsive recipes (DS-04/05)", + "chapter": "Theme.md", + "line": 229, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "TH-07", + "title": "Documentation, package contents and local canary (DS-06)", + "chapter": "Theme.md", + "line": 255, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "TH-08", + "title": "Export canonical static assets for public-feed-only and native consumers (DS-05/06)", + "chapter": "Theme.md", + "line": 278, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "TH-09", + "title": "Publish G1 and govern shared extraction (DS-05/06)", + "chapter": "Theme.md", + "line": 330, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "SEC-01", + "title": "Isolate Add/Rotate targets and pending editor lifetimes", + "chapter": "Secrets.md", + "line": 35, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "SEC-02", + "title": "Adopt the shared Theme field and state API", + "chapter": "Secrets.md", + "line": 71, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "SEC-03", + "title": "Make deletion keyboard accessible inside real hosts", + "chapter": "Secrets.md", + "line": 99, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "SEC-04", + "title": "Separate list loading, commit and refresh outcomes", + "chapter": "Secrets.md", + "line": 129, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "SEC-05", + "title": "Improve metadata scanning and row-action context", + "chapter": "Secrets.md", + "line": 159, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "SEC-06", + "title": "Keep reveal outcomes discoverable without announcing plaintext", + "chapter": "Secrets.md", + "line": 185, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "SEC-07", + "title": "Package and host integration evidence", + "chapter": "Secrets.md", + "line": 209, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "OV-01", + "title": "Adopt shared ink and retain readable stale evidence", + "chapter": "Overview.md", + "line": 36, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "OV-02", + "title": "Show every check's textual state", + "chapter": "Overview.md", + "line": 48, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "OV-03", + "title": "Make pause describe display adoption", + "chapter": "Overview.md", + "line": 80, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "OV-04", + "title": "Separate stale and unreachable group counts", + "chapter": "Overview.md", + "line": 106, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "OV-05", + "title": "Make complete diagnostic errors available by disclosure", + "chapter": "Overview.md", + "line": 132, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "OV-06", + "title": "Add optional exception focus and explicit UTC sweep time", + "chapter": "Overview.md", + "line": 157, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "OV-07", + "title": "Family acceptance and rollout record", + "chapter": "Overview.md", + "line": 186, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "SB-00", + "title": "Compatibility adoption and baseline captures", + "chapter": "ScadaBridge.md", + "line": 49, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "SB-01", + "title": "Name reusable dialogs and prompt fields", + "chapter": "ScadaBridge.md", + "line": 59, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "SB-02", + "title": "Pilot robust modal keyboard behavior in audit drawer", + "chapter": "ScadaBridge.md", + "line": 79, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "SB-03", + "title": "Wire labels, hints and errors across forms and filters", + "chapter": "ScadaBridge.md", + "line": 91, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "SB-04", + "title": "Make audit custom windows explicitly UTC", + "chapter": "ScadaBridge.md", + "line": 102, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "SB-05", + "title": "Preserve independent dashboard count states", + "chapter": "ScadaBridge.md", + "line": 120, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "SB-06", + "title": "Name notification controls and retain recovery", + "chapter": "ScadaBridge.md", + "line": 129, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "SB-07", + "title": "Adopt semantic text inks in light and dark", + "chapter": "ScadaBridge.md", + "line": 137, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "SB-08", + "title": "Standardize page and table hierarchy", + "chapter": "ScadaBridge.md", + "line": 148, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "SB-09", + "title": "Correct empty counts and contain table overflow", + "chapter": "ScadaBridge.md", + "line": 158, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "SB-10", + "title": "Make dashboard destinations match authorization", + "chapter": "ScadaBridge.md", + "line": 179, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "SB-11", + "title": "Make operational summaries easier to scan", + "chapter": "ScadaBridge.md", + "line": 188, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "SB-12", + "title": "Adapt topology density and scroll composition", + "chapter": "ScadaBridge.md", + "line": 198, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "SB-13", + "title": "Reconcile theme palette ownership safely", + "chapter": "ScadaBridge.md", + "line": 208, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "SB-14", + "title": "Simplify audit filters and refuse invalid exact ids", + "chapter": "ScadaBridge.md", + "line": 219, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "SB-15", + "title": "Consolidate domain status visuals and final acceptance", + "chapter": "ScadaBridge.md", + "line": 239, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "OT-01", + "title": "Adopt shared API and label the first driver/filter surfaces", + "chapter": "OtOpcUa.md", + "line": 39, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "OT-02", + "title": "Pilot accessible modal lifecycle on confirmations", + "chapter": "OtOpcUa.md", + "line": 67, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "OT-03", + "title": "Name tree controls without sacrificing virtualization", + "chapter": "OtOpcUa.md", + "line": 101, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "OT-04", + "title": "Replace placeholder home with role-appropriate task orientation", + "chapter": "OtOpcUa.md", + "line": 133, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "OT-05", + "title": "Group navigation and retire ordinary Namespace links", + "chapter": "OtOpcUa.md", + "line": 145, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "OT-06", + "title": "Standardize page/table grammar across routes", + "chapter": "OtOpcUa.md", + "line": 173, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "OT-07", + "title": "Make toolbars and dense trees usable on narrow/touch layouts", + "chapter": "OtOpcUa.md", + "line": 187, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "OT-08", + "title": "Expose full errors and audit details without hover", + "chapter": "OtOpcUa.md", + "line": 199, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "OT-09", + "title": "Distinguish request acceptance and deployment application", + "chapter": "OtOpcUa.md", + "line": 227, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "OT-10", + "title": "Explain loaded-tree filtering and provide root retry", + "chapter": "OtOpcUa.md", + "line": 254, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "OT-11", + "title": "Add readable live-tail pause and stale refresh outcomes", + "chapter": "OtOpcUa.md", + "line": 286, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "OT-12", + "title": "Normalize icons and status aliases after behavioral fixes", + "chapter": "OtOpcUa.md", + "line": 319, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "OT-13", + "title": "Roll field associations through every protocol family", + "chapter": "OtOpcUa.md", + "line": 331, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "OT-14", + "title": "Family consistency and release gate", + "chapter": "OtOpcUa.md", + "line": 347, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "MX-01", + "title": "Make tree expansion and watching explicit", + "chapter": "MxAccessGateway.md", + "line": 85, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "MX-02", + "title": "Pilot native dialogs with actual focus management", + "chapter": "MxAccessGateway.md", + "line": 129, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "MX-03", + "title": "Label and recover browse search", + "chapter": "MxAccessGateway.md", + "line": 199, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "MX-04", + "title": "Make overview prioritize faults while preserving counters", + "chapter": "MxAccessGateway.md", + "line": 228, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "MX-05", + "title": "Adopt shared ink and remove duplicated visual rules", + "chapter": "MxAccessGateway.md", + "line": 257, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "MX-06", + "title": "Expose safe errors and retry without losing context", + "chapter": "MxAccessGateway.md", + "line": 288, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "MX-07", + "title": "Apply shared coarse-pointer and containment rules", + "chapter": "MxAccessGateway.md", + "line": 335, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "MX-08", + "title": "Normalize destination and action language", + "chapter": "MxAccessGateway.md", + "line": 364, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "HG-01", + "title": "Associate all history and diagnostic fields", + "chapter": "HistorianGateway.md", + "line": 62, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "HG-02", + "title": "Show sampled time and recover unexpected refresh failures", + "chapter": "HistorianGateway.md", + "line": 108, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "HG-03", + "title": "Make health and member detail accessible without hover", + "chapter": "HistorianGateway.md", + "line": 161, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "HG-04", + "title": "Review diagnostic writes before dispatch", + "chapter": "HistorianGateway.md", + "line": 191, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "HG-05", + "title": "Name Galaxy filtering and expansion controls", + "chapter": "HistorianGateway.md", + "line": 240, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "HG-06", + "title": "Keep submitted query context separate from editable draft", + "chapter": "HistorianGateway.md", + "line": 269, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "HG-07", + "title": "Flatten signposts without duplicating status", + "chapter": "HistorianGateway.md", + "line": 315, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "BT-00", + "title": "Capture and adopt the validated shared package", + "chapter": "BTDB.md", + "line": 48, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "BT-01", + "title": "Restore full modal keyboard behavior in two local adapters", + "chapter": "BTDB.md", + "line": 58, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "BT-02", + "title": "Connect field labels, validation and editor names", + "chapter": "BTDB.md", + "line": 71, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "BT-03", + "title": "Guard dirty navigation without changing save transactions", + "chapter": "BTDB.md", + "line": 92, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "BT-04", + "title": "Migrate semantic ink and preserve teal identity", + "chapter": "BTDB.md", + "line": 122, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "BT-05", + "title": "Finish machine-form tab behavior", + "chapter": "BTDB.md", + "line": 133, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "BT-06", + "title": "Adapt forms and row dialogs for phone/touch", + "chapter": "BTDB.md", + "line": 143, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "BT-07", + "title": "Recover from failed Monaco initialization", + "chapter": "BTDB.md", + "line": 153, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "BT-08", + "title": "Reconcile shared page anatomy and version compatibility", + "chapter": "BTDB.md", + "line": 163, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "BT-09", + "title": "State UTC before date entry and retain precision", + "chapter": "BTDB.md", + "line": 174, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "BT-10", + "title": "Remove misleading sort cues and verify table scale", + "chapter": "BTDB.md", + "line": 184, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "BT-11", + "title": "Promote the review workflow and complete suite acceptance", + "chapter": "BTDB.md", + "line": 194, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "OEE-01", + "title": "Give Jobs details a semantic keyboard disclosure", + "chapter": "ignitionoee.md", + "line": 67, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "OEE-02", + "title": "Pilot complete native modal behavior in router", + "chapter": "ignitionoee.md", + "line": 116, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "OEE-03", + "title": "Import canonical static assets without a private registry feed", + "chapter": "ignitionoee.md", + "line": 208, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "OEE-04", + "title": "Map shared tokens into native Perspective views", + "chapter": "ignitionoee.md", + "line": 250, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "OEE-05", + "title": "Keep long router navigation and sign-out reachable", + "chapter": "ignitionoee.md", + "line": 287, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "OEE-06", + "title": "Preserve scope across related scheduling screens", + "chapter": "ignitionoee.md", + "line": 315, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "OEE-07", + "title": "Standardize issue-state feedback without hiding consequences", + "chapter": "ignitionoee.md", + "line": 368, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "OEE-08", + "title": "Reuse wrapping toolbar/table contracts across router", + "chapter": "ignitionoee.md", + "line": 400, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "OEE-09", + "title": "Keep eligibility and verification semantics distinct from health", + "chapter": "ignitionoee.md", + "line": 433, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + }, + { + "id": "OEE-10", + "title": "Propagate operator touch density through reason entry", + "chapter": "ignitionoee.md", + "line": 475, + "status": "planned", + "prerequisiteGates": [ + "GB" + ], + "dependencies": "GB is mandatory before every UI task; additional G1/G2/chapter dependencies remain in the master and named task." + } + ], + "coverage": [ + { + "finding": "DS-01", + "report": "impeccable/SHARED-DESIGN-SYSTEM.md", + "chapter": "Theme.md", + "tasks": [ + "TH-02", + "TH-07" + ] + }, + { + "finding": "DS-02", + "report": "impeccable/SHARED-DESIGN-SYSTEM.md", + "chapter": "Theme.md", + "tasks": [ + "TH-03" + ] + }, + { + "finding": "DS-03", + "report": "impeccable/SHARED-DESIGN-SYSTEM.md", + "chapter": "Theme.md", + "tasks": [ + "TH-04" + ] + }, + { + "finding": "DS-04", + "report": "impeccable/SHARED-DESIGN-SYSTEM.md", + "chapter": "Theme.md", + "tasks": [ + "TH-05", + "TH-06" + ] + }, + { + "finding": "DS-05", + "report": "impeccable/SHARED-DESIGN-SYSTEM.md", + "chapter": "Theme.md", + "tasks": [ + "TH-06", + "TH-08", + "TH-09" + ] + }, + { + "finding": "DS-06", + "report": "impeccable/SHARED-DESIGN-SYSTEM.md", + "chapter": "Theme.md", + "tasks": [ + "TH-01", + "TH-07", + "TH-08", + "TH-09" + ] + }, + { + "finding": "SEC-06", + "report": "impeccable/Secrets.md", + "chapter": "Secrets.md", + "tasks": [ + "SEC-01", + "SEC-07" + ] + }, + { + "finding": "SEC-01", + "report": "impeccable/Secrets.md", + "chapter": "Secrets.md", + "tasks": [ + "SEC-02", + "SEC-07" + ] + }, + { + "finding": "SEC-02", + "report": "impeccable/Secrets.md", + "chapter": "Secrets.md", + "tasks": [ + "SEC-03", + "SEC-07" + ] + }, + { + "finding": "SEC-03", + "report": "impeccable/Secrets.md", + "chapter": "Secrets.md", + "tasks": [ + "SEC-04", + "SEC-07" + ] + }, + { + "finding": "SEC-04", + "report": "impeccable/Secrets.md", + "chapter": "Secrets.md", + "tasks": [ + "SEC-05", + "SEC-07" + ] + }, + { + "finding": "SEC-05", + "report": "impeccable/Secrets.md", + "chapter": "Secrets.md", + "tasks": [ + "SEC-06", + "SEC-07" + ] + }, + { + "finding": "OV-01", + "report": "impeccable/Overview.md", + "chapter": "Overview.md", + "tasks": [ + "OV-01", + "OV-07" + ] + }, + { + "finding": "OV-02", + "report": "impeccable/Overview.md", + "chapter": "Overview.md", + "tasks": [ + "OV-02", + "OV-07" + ] + }, + { + "finding": "OV-03", + "report": "impeccable/Overview.md", + "chapter": "Overview.md", + "tasks": [ + "OV-03", + "OV-07" + ] + }, + { + "finding": "OV-04", + "report": "impeccable/Overview.md", + "chapter": "Overview.md", + "tasks": [ + "OV-04", + "OV-07" + ] + }, + { + "finding": "OV-05", + "report": "impeccable/Overview.md", + "chapter": "Overview.md", + "tasks": [ + "OV-05", + "OV-07" + ] + }, + { + "finding": "OV-06", + "report": "impeccable/Overview.md", + "chapter": "Overview.md", + "tasks": [ + "OV-06", + "OV-07" + ] + }, + { + "finding": "SB-01", + "report": "impeccable/ScadaBridge.md", + "chapter": "ScadaBridge.md", + "tasks": [ + "SB-01" + ] + }, + { + "finding": "SB-02", + "report": "impeccable/ScadaBridge.md", + "chapter": "ScadaBridge.md", + "tasks": [ + "SB-02" + ] + }, + { + "finding": "SB-03", + "report": "impeccable/ScadaBridge.md", + "chapter": "ScadaBridge.md", + "tasks": [ + "SB-03" + ] + }, + { + "finding": "SB-04", + "report": "impeccable/ScadaBridge.md", + "chapter": "ScadaBridge.md", + "tasks": [ + "SB-04" + ] + }, + { + "finding": "SB-05", + "report": "impeccable/ScadaBridge.md", + "chapter": "ScadaBridge.md", + "tasks": [ + "SB-05" + ] + }, + { + "finding": "SB-06", + "report": "impeccable/ScadaBridge.md", + "chapter": "ScadaBridge.md", + "tasks": [ + "SB-06" + ] + }, + { + "finding": "SB-07", + "report": "impeccable/ScadaBridge.md", + "chapter": "ScadaBridge.md", + "tasks": [ + "SB-07" + ] + }, + { + "finding": "SB-08", + "report": "impeccable/ScadaBridge.md", + "chapter": "ScadaBridge.md", + "tasks": [ + "SB-08" + ] + }, + { + "finding": "SB-09", + "report": "impeccable/ScadaBridge.md", + "chapter": "ScadaBridge.md", + "tasks": [ + "SB-09" + ] + }, + { + "finding": "SB-10", + "report": "impeccable/ScadaBridge.md", + "chapter": "ScadaBridge.md", + "tasks": [ + "SB-10" + ] + }, + { + "finding": "SB-11", + "report": "impeccable/ScadaBridge.md", + "chapter": "ScadaBridge.md", + "tasks": [ + "SB-11" + ] + }, + { + "finding": "SB-12", + "report": "impeccable/ScadaBridge.md", + "chapter": "ScadaBridge.md", + "tasks": [ + "SB-12" + ] + }, + { + "finding": "SB-13", + "report": "impeccable/ScadaBridge.md", + "chapter": "ScadaBridge.md", + "tasks": [ + "SB-13" + ] + }, + { + "finding": "SB-14", + "report": "impeccable/ScadaBridge.md", + "chapter": "ScadaBridge.md", + "tasks": [ + "SB-14" + ] + }, + { + "finding": "SB-15", + "report": "impeccable/ScadaBridge.md", + "chapter": "ScadaBridge.md", + "tasks": [ + "SB-15" + ] + }, + { + "finding": "OT-01", + "report": "impeccable/OtOpcUa.md", + "chapter": "OtOpcUa.md", + "tasks": [ + "OT-01", + "OT-13", + "OT-14" + ] + }, + { + "finding": "OT-02", + "report": "impeccable/OtOpcUa.md", + "chapter": "OtOpcUa.md", + "tasks": [ + "OT-02", + "OT-13", + "OT-14" + ] + }, + { + "finding": "OT-03", + "report": "impeccable/OtOpcUa.md", + "chapter": "OtOpcUa.md", + "tasks": [ + "OT-03", + "OT-07", + "OT-14" + ] + }, + { + "finding": "OT-04", + "report": "impeccable/OtOpcUa.md", + "chapter": "OtOpcUa.md", + "tasks": [ + "OT-04", + "OT-14" + ] + }, + { + "finding": "OT-05", + "report": "impeccable/OtOpcUa.md", + "chapter": "OtOpcUa.md", + "tasks": [ + "OT-05", + "OT-14" + ] + }, + { + "finding": "OT-06", + "report": "impeccable/OtOpcUa.md", + "chapter": "OtOpcUa.md", + "tasks": [ + "OT-06", + "OT-14" + ] + }, + { + "finding": "OT-07", + "report": "impeccable/OtOpcUa.md", + "chapter": "OtOpcUa.md", + "tasks": [ + "OT-07", + "OT-14" + ] + }, + { + "finding": "OT-08", + "report": "impeccable/OtOpcUa.md", + "chapter": "OtOpcUa.md", + "tasks": [ + "OT-08", + "OT-14" + ] + }, + { + "finding": "OT-09", + "report": "impeccable/OtOpcUa.md", + "chapter": "OtOpcUa.md", + "tasks": [ + "OT-09", + "OT-14" + ] + }, + { + "finding": "OT-10", + "report": "impeccable/OtOpcUa.md", + "chapter": "OtOpcUa.md", + "tasks": [ + "OT-10", + "OT-14" + ] + }, + { + "finding": "OT-11", + "report": "impeccable/OtOpcUa.md", + "chapter": "OtOpcUa.md", + "tasks": [ + "OT-11", + "OT-14" + ] + }, + { + "finding": "OT-12", + "report": "impeccable/OtOpcUa.md", + "chapter": "OtOpcUa.md", + "tasks": [ + "OT-12", + "OT-14" + ] + }, + { + "finding": "MX-01", + "report": "impeccable/MxAccessGateway.md", + "chapter": "MxAccessGateway.md", + "tasks": [ + "MX-01" + ] + }, + { + "finding": "MX-02", + "report": "impeccable/MxAccessGateway.md", + "chapter": "MxAccessGateway.md", + "tasks": [ + "MX-02" + ] + }, + { + "finding": "MX-03", + "report": "impeccable/MxAccessGateway.md", + "chapter": "MxAccessGateway.md", + "tasks": [ + "MX-03" + ] + }, + { + "finding": "MX-04", + "report": "impeccable/MxAccessGateway.md", + "chapter": "MxAccessGateway.md", + "tasks": [ + "MX-04" + ] + }, + { + "finding": "MX-05", + "report": "impeccable/MxAccessGateway.md", + "chapter": "MxAccessGateway.md", + "tasks": [ + "MX-05" + ] + }, + { + "finding": "MX-06", + "report": "impeccable/MxAccessGateway.md", + "chapter": "MxAccessGateway.md", + "tasks": [ + "MX-06" + ] + }, + { + "finding": "MX-07", + "report": "impeccable/MxAccessGateway.md", + "chapter": "MxAccessGateway.md", + "tasks": [ + "MX-07" + ] + }, + { + "finding": "MX-08", + "report": "impeccable/MxAccessGateway.md", + "chapter": "MxAccessGateway.md", + "tasks": [ + "MX-08" + ] + }, + { + "finding": "HG-01", + "report": "impeccable/HistorianGateway.md", + "chapter": "HistorianGateway.md", + "tasks": [ + "HG-01" + ] + }, + { + "finding": "HG-02", + "report": "impeccable/HistorianGateway.md", + "chapter": "HistorianGateway.md", + "tasks": [ + "HG-02" + ] + }, + { + "finding": "HG-03", + "report": "impeccable/HistorianGateway.md", + "chapter": "HistorianGateway.md", + "tasks": [ + "HG-03" + ] + }, + { + "finding": "HG-04", + "report": "impeccable/HistorianGateway.md", + "chapter": "HistorianGateway.md", + "tasks": [ + "HG-04" + ] + }, + { + "finding": "HG-05", + "report": "impeccable/HistorianGateway.md", + "chapter": "HistorianGateway.md", + "tasks": [ + "HG-05" + ] + }, + { + "finding": "HG-06", + "report": "impeccable/HistorianGateway.md", + "chapter": "HistorianGateway.md", + "tasks": [ + "HG-06" + ] + }, + { + "finding": "HG-07", + "report": "impeccable/HistorianGateway.md", + "chapter": "HistorianGateway.md", + "tasks": [ + "HG-07" + ] + }, + { + "finding": "BT-01", + "report": "impeccable/BTDB.md", + "chapter": "BTDB.md", + "tasks": [ + "BT-01" + ] + }, + { + "finding": "BT-02", + "report": "impeccable/BTDB.md", + "chapter": "BTDB.md", + "tasks": [ + "BT-02" + ] + }, + { + "finding": "BT-03", + "report": "impeccable/BTDB.md", + "chapter": "BTDB.md", + "tasks": [ + "BT-03" + ] + }, + { + "finding": "BT-04", + "report": "impeccable/BTDB.md", + "chapter": "BTDB.md", + "tasks": [ + "BT-04" + ] + }, + { + "finding": "BT-05", + "report": "impeccable/BTDB.md", + "chapter": "BTDB.md", + "tasks": [ + "BT-05" + ] + }, + { + "finding": "BT-06", + "report": "impeccable/BTDB.md", + "chapter": "BTDB.md", + "tasks": [ + "BT-06" + ] + }, + { + "finding": "BT-07", + "report": "impeccable/BTDB.md", + "chapter": "BTDB.md", + "tasks": [ + "BT-07" + ] + }, + { + "finding": "BT-08", + "report": "impeccable/BTDB.md", + "chapter": "BTDB.md", + "tasks": [ + "BT-00", + "BT-08" + ] + }, + { + "finding": "BT-09", + "report": "impeccable/BTDB.md", + "chapter": "BTDB.md", + "tasks": [ + "BT-09" + ] + }, + { + "finding": "BT-10", + "report": "impeccable/BTDB.md", + "chapter": "BTDB.md", + "tasks": [ + "BT-10" + ] + }, + { + "finding": "BT-11", + "report": "impeccable/BTDB.md", + "chapter": "BTDB.md", + "tasks": [ + "BT-11" + ] + }, + { + "finding": "OEE-01", + "report": "impeccable/ignitionoee.md", + "chapter": "ignitionoee.md", + "tasks": [ + "OEE-01" + ] + }, + { + "finding": "OEE-02", + "report": "impeccable/ignitionoee.md", + "chapter": "ignitionoee.md", + "tasks": [ + "OEE-02" + ] + }, + { + "finding": "OEE-03", + "report": "impeccable/ignitionoee.md", + "chapter": "ignitionoee.md", + "tasks": [ + "OEE-03" + ] + }, + { + "finding": "OEE-04", + "report": "impeccable/ignitionoee.md", + "chapter": "ignitionoee.md", + "tasks": [ + "OEE-04" + ] + }, + { + "finding": "OEE-05", + "report": "impeccable/ignitionoee.md", + "chapter": "ignitionoee.md", + "tasks": [ + "OEE-05" + ] + }, + { + "finding": "OEE-06", + "report": "impeccable/ignitionoee.md", + "chapter": "ignitionoee.md", + "tasks": [ + "OEE-06" + ] + }, + { + "finding": "OEE-07", + "report": "impeccable/ignitionoee.md", + "chapter": "ignitionoee.md", + "tasks": [ + "OEE-07" + ] + }, + { + "finding": "OEE-08", + "report": "impeccable/ignitionoee.md", + "chapter": "ignitionoee.md", + "tasks": [ + "OEE-08" + ] + }, + { + "finding": "OEE-09", + "report": "impeccable/ignitionoee.md", + "chapter": "ignitionoee.md", + "tasks": [ + "OEE-09" + ] + }, + { + "finding": "OEE-10", + "report": "impeccable/ignitionoee.md", + "chapter": "ignitionoee.md", + "tasks": [ + "OEE-10" + ] + } + ], + "gates": { + "G0": "Source/test inventory and pre-upgrade baseline", + "GB": { + "requiresTasks": [ + "BU-01", + "BU-02", + "BU-03", + "BU-04", + "BU-05", + "BU-06", + "BU-07", + "BU-08", + "BU-09", + "BU-10" + ], + "blocks": "Every Theme, shared UI, sister UI task and candidate pilot", + "requiredBunitVersion": "2.7.2", + "requiredProjectCount": 7, + "status": "open", + "verifiedProjectCount": 3 + }, + "G1": "Validated shared Theme package and canonical static export, after GB", + "G2": "Two-consumer interaction evidence and extraction decision, after GB", + "G3": "Cross-family implementation and rollout acceptance" + }, + "additionalRequirements": [ + { + "id": "REQ-BUNIT-272", + "description": "Standardize all existing bUnit users on exact stable 2.7.2 first, including dependency compatibility, API/test migration and runtime verification.", + "tasks": [ + "BU-01", + "BU-02", + "BU-03", + "BU-04", + "BU-05", + "BU-06", + "BU-07", + "BU-08", + "BU-09", + "BU-10" + ] + } + ], + "executionWorktree": "/Users/dohertj2/.codex/worktrees/scada-ui-consistency/scadaproj", + "executionBranch": "codex/scada-ui-consistency" +} diff --git a/impeccable/BTDB.md b/impeccable/BTDB.md new file mode 100644 index 0000000..843f52a --- /dev/null +++ b/impeccable/BTDB.md @@ -0,0 +1,164 @@ +# BTDB Manager — shared-theme review and proposed updates + +Reviewed 2026-11-12. Mode: **Operate**. Source baseline: BTDB `5b89798`. Theme adoption is real: `ZB.MOM.WW.BTDB.Manager.csproj:27` references **ZB.MOM.WW.Theme 0.4.1**, `Components/App.razor:15,43` loads Theme assets/scripts, and `Components/Layout/MainLayout.razor:11` uses ThemeShell with existing product accent **#1b7f8e**. This is a shared-theme consumer, not a standalone visual system. + +[Open batch-edit mockup](mockups/BTDB.html) · [Suite index](index.html) · [Shared direction](SHARED-DESIGN-SYSTEM.md) + +## Direction and integrity verdict + +**Preserve Technical-Light and the BTDB teal identity; strengthen shared interaction contracts.** BTDB is already one of the more consistent consumers: common rail, IBM Plex, shared tables/panels/status vocabulary, explicit audit flows, meaningful errors and role-aware links. Its greatest gaps are behavioral accessibility, recovery and phone composition. A new visual identity would obscure the work that is already correct. + +Retain audited batch editing, machine/group configuration, preview-before-import, optimistic-concurrency handling, UTC storage/editing, transfer-chain semantics, permission gates, transaction boundaries and the existing PDF audit route. The Manager edits existing batches; the mockup must not imply that it creates production batches. + +## Coverage and limits + +- Inventoried **18 routed page components / 18 routes**, plus 17 other Razor components (35 total). Deep review: shell, shared table/dialog/row editor/JSON editor/date controls, overview, machine form/list, batch search/edit, configuration import and audit patterns. Other page wrappers and repetitive views received a structure scan, listed below. +- Source-only review: no running BTDB server/database was started and no real batch, machine or configuration was modified. Layout/focus findings require browser verification against implementation; the delivered concept is not that verification. +- Existing `docs/mockups/manager_blazor_mockups.html` was read as historical visual context. It embeds Theme 0.4.1 CSS and Google Fonts links; it is a design reference, not a current deployment screenshot. No current UI PNG goldens were found by the screenshot-file scan. +- Detector ran once against the Manager source. [BTDB-detector.json](evidence/BTDB-detector.json) contains eight warnings, all within vendored Monaco. Its example HTML strings and editor CSS do not establish eight BTDB UI defects; do not alter third-party assets simply to silence them. The command returned exit code 2 while emitting valid findings JSON. +- No runtime performance or WCAG conformance score is asserted. Source findings and proposed acceptance checks are separated below. + +## Strengths to preserve + +- Role-aware rail navigation in `Components/Layout/MainLayout.razor:12–51`; batch-editor links are separately policy-gated on Overview (`Pages/Overview/Overview.razor:73–81`) and Batch edits (`Pages/Batches/BatchEdits.razor:70–75`). +- The machine form has a dirty count, change summary, explicit save confirmation and a distinct concurrency conflict with Reload (`Pages/Machines/MachineForm.razor:49–68`). +- Batch search preserves invalid ranges and displays validation instead of clearing input (`Pages/Batches/FindBatch.razor:9–24` and `SearchAsync`). +- Batch save validates the header and row collections, previews a change summary, keeps edits after failure and avoids exposing infrastructure details (`Pages/Batches/BatchEdit.razor:669–726`). +- Configuration import clearly separates source, selection and preview, offers a no-change result, and disables unattributable writes (`Pages/ConfigImport/ConfigImport.razor:24–167`). +- Tables already have local overflow containers (`Components/Shared/DataTable.razor:17–38`), unlike several sister-screen patterns. Editable row Cancel restores clones where supplied, and production work-order/cycle editors supply `Clone` (`BatchEdit.razor:130–133,180–183`). +- JSON assets are vendored and lazily loaded; formatting/validation is task-related rather than decoration (`Components/Shared/JsonEditor.razor:1–15`). Keep that ownership and loading strategy. + +## Prioritized recommendations + +All source paths below are relative to `BTDB/src/ZB.MOM.WW.BTDB.Manager/`. + +### BT-01 · P1 · Complete modal focus containment and return + +**Evidence:** `Components/Shared/DialogHost.razor:9–13` explicitly says body scroll lock and focus-trap helpers were omitted; `:80–115` moves initial focus and handles Escape only. `Components/Shared/EditableRows.razor:92–109,225–231,258–279` likewise has a labelled modal and initial focus but no Tab containment or focus restoration. + +**Impact:** A keyboard user can leave a visually modal confirmation/editor and lose the row context on closing. `aria-modal=true` does not implement focus behavior. + +**Ownership/recommendation:** Local modal adapters, one shared overlay contract. Add focus containment, inert background treatment, scroll lock and return-to-trigger; consider a tested native dialog implementation where compatible with Blazor forms. Keep cloned row rollback and Escape cancellation. **Acceptance:** open, edit, Tab/Shift+Tab, Cancel/Escape/Done and return to the initiating row in both small and wide dialogs; background controls remain unreachable while modal. WCAG 2.1.1 / 2.4.3. `$impeccable harden`. + +### BT-02 · P1 · Give every form/filter a persistent accessible label + +**Evidence:** `Pages/Machines/MachineForm.razor:76–103,120–122` places labels adjacent to inputs/selects without id/for relationships. Work-order popup fields repeat this at `Pages/Batches/BatchEdit.razor:149–171`. Machines search/group filter are placeholder-only/unlabelled in `Pages/Machines/MachinesList.razor:42–50`. Shared prompt `Components/Shared/DialogHost.razor:35–37` also lacks label linkage. The core batch header correctly demonstrates id/for at `BatchEdit.razor:80–103`. + +**Impact:** Forms mode and populated filters lack the visible context offered to sighted readers. + +**Ownership/recommendation:** Shared control contracts plus local callsites. Connect labels, hints and validation with stable ids and `aria-describedby`; pass an accessible name to Monaco rather than leaving a generic editor name. **Acceptance:** all controls expose meaningful visible-label names and invalid-state descriptions; duplicate row editors have unique ids. WCAG 1.3.1 / 3.3.2 / 4.1.2. `$impeccable harden`. + +### BT-03 · P1 · Protect unsaved edits across navigation + +**Evidence:** `MachineForm.razor:49–51` and `BatchEdit.razor:69–72` display unsaved changes; a source search across Components and nonvendored wwwroot found no NavigationLock, beforeunload handler or equivalent navigation guard. The dirty note alone does not prevent leaving through the rail or refreshing. + +**Impact:** A user can spend time correcting a batch and leave unintentionally. This is a source-observed missing safeguard; actual browser data loss should be confirmed with a disposable record. + +**Ownership/recommendation:** Local form-state guard with shared confirmation presentation. Warn only when a form is dirty; offer Stay / Discard and leave, and preserve the existing successful-save navigation. Never imply a draft is persisted unless storage exists. **Acceptance:** rail click, browser Back, refresh, Cancel and successful save have intentional behavior for clean/dirty forms; row-popup cancellation still restores its snapshot. `$impeccable harden`. + +### BT-04 · P1 · Replace faint/status text foregrounds with accessible tokens + +**Evidence:** `wwwroot/css/site.css:58,80` uses shared faint ink for JSON captions and dismiss controls; `Pages/ConfigImport/ConfigImport.razor.css:7–10,31–33` uses faint ink for guidance; `.chip.added` at `site.css:67` uses shared `--ok` on `--ok-bg`. The Theme 0.4.1 source/reference palette uses faint #8b9097 and green #2f9e44; these normal-size foregrounds do not reach 4.5:1 on their light surfaces. Decorative dots can keep their existing chroma. + +**Impact:** Small operational hints and result labels are difficult to read. **Ownership/recommendation:** Fix semantic text tokens in Theme, then migrate local usages. Preserve teal as a product accent while using the same status text colors across the suite. **Acceptance:** actual computed caption, disabled/help/error/state pairs meet required contrast in supported themes and all status meaning has text. WCAG 1.4.3. `$impeccable colorize`. + +### BT-05 · P2 · Finish tab semantics and keyboard behavior + +**Evidence:** `Pages/Machines/MachineForm.razor:130–151` supplies tablist/tab/tabpanel roles and selected state but no tab/panel ids, aria-controls/labelledby relationships, roving tabindex or arrow-key handler (source search confirmed no keyboard handler in this form). + +**Impact:** Tabs look familiar while exposing an incomplete assistive/keyboard model. **Ownership/recommendation:** Share a tab pattern; add relationships, one tab stop and Left/Right/Home/End behavior, retaining hidden panel content to preserve drafts. Alternatively use ordinary disclosure buttons with honest expanded-state semantics. **Acceptance:** keyboard reaches and changes each panel predictably; no draft disappears when switching panels. `$impeccable harden`. + +### BT-06 · P2 · Add a single-column phone layout and practical touch density + +**Evidence:** `wwwroot/css/site.css:30–32,97–102` defines two-column fields and three-column variant, but only reduces three columns to two at 900px. `.check-row` at `:34` does not wrap. Wide row dialogs use 80vw at `:95`, further narrowing the two-column form on a phone. Config import has its own one-column breakpoint (`ConfigImport.razor.css:13–22`), showing the intended adaptation is possible. + +**Impact:** Long field names, timezone selections and checkbox groups compete for a small remaining width. **Ownership/recommendation:** Shared form/density tokens, local grids. At phone width make forms one column, use near-full-width dialogs with bounded body scrolling and keep actions visible; allow checkbox groups to wrap. Keep compact fine-pointer desktop rows, increase coarse-pointer targets. **Acceptance:** 390×844, 768×1024, short landscape and 200% zoom show complete fields/validation without page overflow or clipped actions; touch controls have at least 44px practical targets. `$impeccable adapt`. + +### BT-07 · P2 · Surface JSON editor initialization failure + +**Evidence:** `Components/Shared/JsonEditor.razor:29,62–84` renders an empty host and logs JS initialization failure; it has no loading/error/fallback branch. `wwwroot/js/json-editor.js:62` creates Monaco without a field-specific ariaLabel option. + +**Impact:** A failed worker/script request leaves an unexplained blank area. **Ownership/recommendation:** Local editor wrapper. Expose initialization status, Retry and a labelled plain-text fallback preserving the bound value, or make the failure explicit if fallback is unsupported. Keep server JSON validation. **Acceptance:** blocked Monaco asset, slow load and circuit interruption show a visible recoverable state with no value loss; keyboard and screen reader receive the field name. `$impeccable harden`. + +### BT-08 · P2 · Align the pinned package and shared page anatomy deliberately + +**Evidence:** Theme pin is 0.4.1; local `wwwroot/css/site.css:27` defines `.page-head` as a compact flex row while newer Theme uses a shared page-head pattern. The canonical Theme README documents mobile shell containment fixes in 0.5.0 and scroll-height fixes through 0.5.3. This version gap establishes a migration need, not a measured BTDB runtime failure. + +**Impact:** Older shared shell behavior and duplicate class ownership can diverge from the suite or change unexpectedly during a version bump. + +**Ownership/recommendation:** Theme release coordination plus local migration. Upgrade to the suite-agreed tested release after comparing token/layout changes; reconcile `.page-head` ownership, preserve the teal accent and remove only demonstrably redundant local rules. Keep custom editable-row/diff/domain code in BTDB. **Acceptance:** render login, list, machine form, batch edit, import and audit at desktop/mobile before and after; rail/content remain visible with mobile nav closed, fonts resolve locally and no footer overflow appears. `$impeccable extract` / `$impeccable adapt`. + +### BT-09 · P2 · Make dates explicit before the search runs + +**Evidence:** `Pages/Batches/FindBatch.razor:49–55` labels range fields “Started after/before”; the UTC statement only appears after `_searched` at `:59–63`. The shared `DateTimeRangeFilter.razor:14–27` uses timezone-free datetime-local controls and forwards raw DateTime values. Batch header editing explicitly says UTC (`BatchEdit.razor:81,88`), while Machine TimeZone is report-time-only (`MachineForm.razor:104`). + +**Impact:** An operator may assume their machine/browser zone when entering an initial search window. **Ownership/recommendation:** Shared date-range policy with local wording. State “Start time window (UTC)” before entry, use consistent timezone labels on result/export, and retain explicit precision for audited edits. Do not silently adopt the browser zone or Machine.TimeZone for stored batch edits. **Acceptance:** a known UTC batch matches the same filter from differing browser zones; report conversion remains distinct and documented. `$impeccable clarify`. + +### BT-10 · P2 · Remove false sort cues and improve table navigation + +**Evidence:** `Pages/Machines/MachinesList.razor:58` marks Code `.sortable`, while shared `DataTable.razor:8–13` explicitly does not implement sorting and the heading has no sort control. The component's overflow wrapper at `:17` has no region name/tabindex. `Pages/Batches/BatchEdits.razor:11–19` documents loading the whole audit-edit table and client-side filtering. + +**Impact:** A sort appearance implies an action that is unavailable; large audit histories can create avoidable loading/rendering costs. **Ownership/recommendation:** Local sorting/query behavior with shared table semantics. Remove the sortable class until a real keyboard button exists, or implement sortable headings with aria-sort. Label overflow regions and preserve column headers. Measure audit history first; add server-side range filtering/paging if volume warrants it rather than putting generic client pagination into every small table. **Acceptance:** mouse/keyboard sort reflects data order, overflowing tables are keyboard reachable, zero/one/many results remain clear; record a realistic large-history query/render measurement before selecting optimization. `$impeccable clarify`, `$impeccable optimize`. + +### BT-11 · P2 · Put review context above inventory metrics + +**Evidence:** `Pages/Overview/Overview.razor:29–54` opens with six equal aggregate cards before recent edits; the access panel at `:89–121` repeats roles and capabilities already partly visible in the rail. Batch editing already has a valuable change summary and explicit edit note. + +**Impact:** Frequent users spend the first scan on inventory rather than the batch/review task. **Ownership/recommendation:** Local information hierarchy, shared summary/list styles. Use a compact facts strip, promote recent edits and a role-appropriate “Find a batch” action, and give the changed values/reason/save outcome the strongest hierarchy on the edit screen. Keep access details available without dominating the first viewport. No new real-time batch monitor is implied. **Acceptance:** users can find a batch, identify pending changes and review their reason within one coherent path; Viewer still has read-only destinations. `$impeccable distill`, then `$impeccable polish`. + +## Recommended rollout and state checks + +1. Shared Theme: accessible text/status tokens, page/form/table/overlay contracts, responsive density and suite version policy. Maintain each product's existing accent. +2. Correctness/accessibility: BT-01–05, BT-07 and initial zone guidance BT-09. Keep all SQL/role/audit protections unchanged. +3. Layout/migration: BT-06 and BT-08, then BT-10/11. Finish with `$impeccable polish` and re-run `$impeccable audit` after implementation. + +| Surface | Required states in implementation verification | +|---|---| +| Shell/login/access denied/error | Mobile nav open/closed; missing assets; expired session; unauthorized destination; sign-in error | +| Machines/groups list and forms | Loading failure/retry; no configured records vs filtered zero; inactive; long names; field error; dirty navigation; conflicting edit; rollback | +| Find batch/batch edit | Missing machine/range; inverted range; no results; open batch; header/child-row errors; removed/restored row; failed save; stale version; successful audit attribution | +| Transfers/lot context | Outgoing transfer target, inbound sources, read-only lot path, invalid transfer; never imply batch creation | +| Configuration import | No source; load/preview failure; empty selection; no changes; stale preview; blocked import; missing username; apply error/success | +| Audit/PDF | Missing entity; empty history; large history; long payloads; links to machine/batch; UTC timestamps; print/export context | +| JSON/dialogs/toasts | Slow/init failure; invalid JSON; keyboard editor escape; modal focus return; no lost value; persistent critical recovery text | + +Run one batched implementation inspection at 1440×900 / 768×1024 / 390×844 plus 200% zoom, with keyboard and a screen reader, then one correction batch and one confirmation pass. The source contains useful async cancellation and lazy-loading protections; no benchmark has been run and no runtime performance regression is asserted. + +The mockup has safe local form editing, validation, change-review disclosure and discard controls. It labels all data illustrative and contains no production save or service call. You can ask to implement recommendations individually or in the order above. + +## Route inventory + +“Deep” means markup and relevant state/style/component dependencies were inspected; “scanned” means the route and repeated structural pattern were inventoried, not a complete behavioral execution. Nonroutable MachineForm, MachineGroupForm, JsonEditor, EditableRows and other shared controls are included in the evidence above. + +| Component under `Components/Pages/` | Route | Review depth | +|---|---|---| +| `AccessDenied.razor` | `/access-denied` | Scanned | +| `Audit/AuditIndex.razor` | `/audit` | Deep | +| `Audit/BatchEditAudit.razor` | `/audit/batch-edits/{id:int}` | Deep | +| `Audit/MachineAudit.razor` | `/audit/machines/{id:int}` | Deep | +| `Audit/MachineGroupAudit.razor` | `/audit/machine-groups/{id:int}` | Scanned | +| `Batches/BatchEdit.razor` | `/batches/{id:int}/edit` | Deep | +| `Batches/BatchEdits.razor` | `/batch-edits` | Deep | +| `Batches/FindBatch.razor` | `/batches/find` | Deep | +| `ConfigImport/ConfigImport.razor` | `/config-import` | Deep | +| `Error.razor` | `/error` | Scanned | +| `Login.razor` | `/login` | Scanned | +| `MachineGroups/MachineGroupEdit.razor` | `/machine-groups/{id:int}` | Scanned | +| `MachineGroups/MachineGroupNew.razor` | `/machine-groups/new` | Scanned | +| `MachineGroups/MachineGroupsList.razor` | `/machine-groups` | Scanned | +| `Machines/MachineEdit.razor` | `/machines/{id:int}` | Scanned | +| `Machines/MachineNew.razor` | `/machines/new` | Scanned | +| `Machines/MachinesList.razor` | `/machines` | Deep | +| `Overview/Overview.razor` | `/` | Deep | + + +## Rendered proposal previews + +These are proposed UI artifacts with illustrative data, not screenshots of the current application. All use the same shared stylesheet. See [verification and limits](VERIFICATION.md). + +### BTDB + +[Interactive HTML](mockups/BTDB.html) · [Desktop PNG](evidence/BTDB-desktop.png) · [Mobile PNG](evidence/BTDB-mobile.png) + +![Proposed BTDB desktop UI](evidence/BTDB-desktop.png) + diff --git a/impeccable/HistorianGateway.md b/impeccable/HistorianGateway.md new file mode 100644 index 0000000..e0d26fc --- /dev/null +++ b/impeccable/HistorianGateway.md @@ -0,0 +1,106 @@ +# HistorianGateway — Impeccable UI recommendations + +Reviewed 2026-11-12 · source snapshot `fa9cf31` · Operate mode. + +The server consumes Theme **0.5.0** (Server.csproj:30) and uses the shared shell, assets, panels, data tables and status pills. Keep its allowed green product accent (`MainLayout.razor:10`); status meaning remains common with blue-accent sisters. The main opportunity is to make point-in-time state, queries and diagnostic writes clearer. + +[Open proposed mockup](mockups/HistorianGateway.html) · [Review index](index.html) · [Shared direction](SHARED-DESIGN-SYSTEM.md). + +This is a source-backed review and design proposal. Production applications, live credentials, deployed data, browser keyboard behavior, and measured performance were not exercised. Mockups use illustrative data and demonstrate proposed patterns; they are not screenshots of the existing application. No production source was modified. + +## Summary + +1 P1 and 6 P2 recommendations; no demonstrated P0. The architecture already avoids duplicated live status on its landing page and lazily renders Galaxy nodes. Prioritize label associations, accessible diagnostics, freshness and write-intent review. No numerical quality score is assigned without runtime accessibility/performance evidence. + +## Shared visual contract + +Keep IBM Plex Sans for reading and Plex Mono for identifiers, timestamps, and aligned values; warm paper, white panels, thin neutral rules, compact navigation, and one clear page heading. Use the shared Theme package for chrome and primitives. Shared means the same spacing, field, table, notice, focus, status, and responsive rules. Preserve explicitly permitted product accents. Do not fork a theme per page or introduce a separate dark dashboard. The mockups show accessible status ink and taller touch targets as proposals for the shared library, not new app-local token copies. + +## Verification and release gate + +At 1440 × 900, 1024 × 768, 390 × 844 and 200% zoom, verify that only intentional table regions scroll horizontally; headings, filters, notices and footer actions remain visible. Keyboard-test navigation, search, detail disclosure and all dialogs. Confirm text names and state announcements with a screen reader; measure text contrast (4.5:1) and non-text focus/control contrast (3:1). On coarse pointers, offer 44px targets without forcing every desktop data row to become tall. Test long tag paths, empty results, unavailable dependencies, stale snapshots, denied access and a slow operation that succeeds after several seconds. + +A source detector ran once across the gateway dashboard and ignitionoee router/registry component directories. It returned `[]`: see [gateways-detector.json](evidence/gateways-detector.json). This is a narrow mechanical result, not an accessibility pass; manual source findings below remain valid. CSS in separate host asset directories and Perspective JSON are outside that invocation. No detector false positives required dismissal. + +### HG-01 · P1 · Associate every console label and control + +**Evidence:** [src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/HistorianConsolePage.razor:28](/Users/dohertj2/Desktop/HistorianGateway/src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/HistorianConsolePage.razor:28). + +**Owner:** app plus shared field API. **Impact:** query and write-test controls use standalone labels without `for`/`id` or an explicit accessible name; visible proximity does not associate them. **Recommendation:** give each query/write/event field a stable unique ID and associated label, group query vs historical write vs event write with headings/fieldsets, and associate validation help and errors. **Acceptance:** a screen reader announces Tag, Mode, Max values, Start UTC, End UTC and every diagnostic field unambiguously; clicking a label focuses its control. WCAG 1.3.1 / 3.3.2 / 4.1.2. **Command:** `$impeccable harden`. + +### HG-02 · P2 · Place sampled time beside status and preserve stale context on failure + +**Evidence:** [src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/StatusPage.razor:17](/Users/dohertj2/Desktop/HistorianGateway/src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/StatusPage.razor:17). + +**Owner:** app adopting shared page-state/freshness pattern. **Impact:** the page is deliberately manual-refresh, but generated time is buried in the Gateway card (`:62`). A connectivity chip at the top can be read as current after a long unattended interval. `LoadAsync` at `:222` has `try/finally` but no page-local failure UI. Health has the same manual pattern at `HealthPage.razor:17/105`. **Recommendation:** place “Snapshot captured … UTC · Manual refresh” beside the title, preserve the last snapshot on retrieval failure, and show a recovery notice with Retry. **Acceptance:** initial failure, refresh failure and old-but-valid data are visually distinct; retry retains page context; no silent stale-success display. **Command:** `$impeccable harden`. + +### HG-03 · P2 · Make diagnostic errors readable without hover + +**Evidence:** [src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/HealthPage.razor:82](/Users/dohertj2/Desktop/HistorianGateway/src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/HealthPage.razor:82). + +**Owner:** shared disclosure/detail pattern, app content. **Impact:** health descriptions and redundancy errors (`StatusPage.razor:199`) are abbreviated with only a title tooltip exposing the full value. **Recommendation:** a row details disclosure must reveal full safe text, affected dependency and next step; preserve short rows for scanning. **Acceptance:** keyboard/touch users can retrieve the same diagnostic content as a mouse user, copy identifiers, and return to the same row. **Command:** `$impeccable harden`. + +### HG-04 · P2 · Separate and review historical write intent + +**Evidence:** [src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/HistorianConsolePage.razor:130](/Users/dohertj2/Desktop/HistorianGateway/src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/HistorianConsolePage.razor:130). + +**Owner:** app behavior. **Impact:** the Administrator write-test panel sits immediately beneath read-only history results and uses the same secondary-button treatment; a direct Insert value or Send event applies an actual operation. **Recommendation:** retain role gating and diagnostic-only copy; put writes in a clearly labeled disclosure or dedicated section and show a compact review of target, tag, UTC timestamp and operation before dispatch. A review is a new proposed behavior, not existing enforcement. **Acceptance:** queries remain one action; a write requires an explicit review/confirm step, names its target, prevents double-submit and preserves typed data after failure. **Command:** `$impeccable clarify`. + +### HG-05 · P2 · Give Galaxy search and expansion recognizable names + +**Evidence:** [src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/GalaxyBrowserPage.razor:54](/Users/dohertj2/Desktop/HistorianGateway/src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/GalaxyBrowserPage.razor:54). + +**Owner:** app; reusable browse control pattern. **Impact:** search has only placeholder copy. Node buttons in `Shared/GalaxyTreeNodeView.razor:20` expose expanded state correctly but all announce “Toggle”; the clickable node-label span has no keyboard interaction. **Recommendation:** add a visible search label and count/clear control, name each toggle “Expand [object]” or “Collapse [object]”, and consolidate label plus chevron into a semantic button. **Acceptance:** the user can distinguish adjacent node actions and locate search after typing; preserve lazy rendering and the 300-hit cap. **Command:** `$impeccable harden`. + +### HG-06 · P2 · Strengthen query result hierarchy and action feedback + +**Evidence:** [src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/HistorianConsolePage.razor:80](/Users/dohertj2/Desktop/HistorianGateway/src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/HistorianConsolePage.razor:80). + +**Owner:** shared field/notice/table patterns + app. **Impact:** Run is visually equivalent to secondary actions; unsuccessful query text is a muted paragraph (`:88`) and result context is only row count. **Recommendation:** name the primary action Run query, show busy status with `aria-busy`, a single polite result announcement, a distinct failure notice, and retain the submitted tag/range/mode beside results. Show zero samples as a successful empty result with a recovery suggestion. **Acceptance:** keyboard submission is possible; failure is distinguishable from an empty result; editing the next query does not silently relabel the previous result set. **Command:** `$impeccable clarify`. + +### HG-07 · P2 · Flatten landing-page signposts while keeping their purpose + +**Evidence:** [src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/Home.razor:13](/Users/dohertj2/Desktop/HistorianGateway/src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/Home.razor:13). + +**Owner:** app composition. **Impact:** four equally sized panels duplicate rail destinations and require reading paragraphs before navigation. The intentional choice not to duplicate live status is sound. **Recommendation:** keep the landing page a signpost, using a concise grouped task list: Inspect gateway health, Browse Galaxy metadata, Query history; keep admin-only entry points role-gated. Do not add invented live metrics. **Acceptance:** all current destinations remain available and descriptive, and the first viewport distinguishes read-only browsing from diagnostic writing. **Command:** `$impeccable distill`. + +## What to keep + +- The green accent is an existing permitted shell override; it does not justify green variants of every component. +- Server-side role gating around diagnostic writes and API-key administration, one-time tokens and inline revoke confirmation. +- Manual refresh: keep it visible and honest rather than adding hidden polling everywhere. +- Lazy Galaxy rendering with independent expansion state and a capped flat search, which explicitly addresses large real hierarchies. +- Missing archive counts stay `n/a`, not zero (`StatusPage.razor:254`); keep unknown distinct from healthy. + +## Coverage and implementation order + +Deep inspection: Console query/write markup; Status and Health state/data handling; Galaxy browser and recursive node; API-key form; shell and CSS. Login and landing-page routing were scanned. Shared mounted Secrets UI belongs to the family shared-component review. + +| Route | Source | Coverage | +| --- | --- | --- | +| `/apikeys` | `src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/ApiKeysPage.razor` | Source scanned | +| `/galaxy` | `src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/GalaxyBrowserPage.razor` | Source scanned | +| `/health` | `src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/HealthPage.razor` | Source scanned | +| `/console` | `src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/HistorianConsolePage.razor` | Source scanned | +| `/` | `src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/Home.razor` | Source scanned | +| `/login` | `src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/Login.razor` | Source scanned | +| `/status` | `src/ZB.MOM.WW.HistorianGateway.Server/Dashboard/Components/Pages/StatusPage.razor` | Source scanned | + +1. `$impeccable harden`: HG-01, HG-02, HG-03 and HG-05. +2. `$impeccable clarify`: HG-04/06; `$impeccable distill`: HG-07. +3. `$impeccable adapt`: coarse-pointer tree hit areas, horizontal table containment, long targets and 200% zoom. +4. `$impeccable polish`, then a live `$impeccable audit`. + +The mockup focuses on the proposed Console: an explicitly labeled query, submitted-result context, quality text, and a guarded diagnostic-write disclosure. Its “Show sample results” control only reveals local illustrative rows and never contacts a historian. + + +## Rendered proposal previews + +These are proposed UI artifacts with illustrative data, not screenshots of the current application. All use the same shared stylesheet. See [verification and limits](VERIFICATION.md). + +### HistorianGateway + +[Interactive HTML](mockups/HistorianGateway.html) · [Desktop PNG](evidence/HistorianGateway-desktop.png) · [Mobile PNG](evidence/HistorianGateway-mobile.png) + +![Proposed HistorianGateway desktop UI](evidence/HistorianGateway-desktop.png) + diff --git a/impeccable/IMPLEMENTATION-PLAN.md b/impeccable/IMPLEMENTATION-PLAN.md new file mode 100644 index 0000000..fcfb831 --- /dev/null +++ b/impeccable/IMPLEMENTATION-PLAN.md @@ -0,0 +1,11 @@ +# Implementation plan + +The detailed plan, with bUnit standardization before shared-theme work, is saved at: + +[SCADA Family UI Consistency Implementation Plan](../docs/plans/2026-11-12-scada-ui-consistency.md) + +It contains the dependency order, shared API/token decisions, release gates, adoption matrix, verification requirements and rollback rules. It begins with a mandatory [bUnit 2.7.2 phase](../docs/plans/2026-11-12-scada-ui-consistency/BUnit.md) covering all seven existing bUnit test projects, dependency compatibility, API migration and verification before the shared Theme. Its remaining project chapters cover Theme, Secrets UI, Overview, ScadaBridge, OtOpcUa, MxAccessGateway, HistorianGateway, BTDB and ignitionoee (router, registry and native Perspective). + +The chapters map every recommendation to implementation tasks with exact files, regression tests, commands, expected outcomes, visual checks and commits. [Task ledger](../docs/plans/2026-11-12-scada-ui-consistency/tasks.json) records planned work; [source baselines](../docs/plans/2026-11-12-scada-ui-consistency/source-baselines.json) records revision drift since the review. + +Planning only: no application source was changed, tests were not run, and no package was published or deployed. The mockups remain illustrative visual references rather than copy-and-paste production pages. diff --git a/impeccable/MxAccessGateway.md b/impeccable/MxAccessGateway.md new file mode 100644 index 0000000..d0e52d0 --- /dev/null +++ b/impeccable/MxAccessGateway.md @@ -0,0 +1,115 @@ +# MxAccessGateway — Impeccable UI recommendations + +Reviewed 2026-11-12 · source snapshot `7481b959` · Operate mode. + +The dashboard already consumes `ZB.MOM.WW.Theme` **0.5.0** (Server.csproj:18), with `ThemeHead`, `ThemeScripts`, `ThemeShell`, and an app-local state adapter wrapping `StatusPill`. Keep its blue accent. The highest-value update is to make Galaxy browsing as usable by keyboard and touch as it is by mouse. + +[Open proposed mockup](mockups/MxAccessGateway.html) · [Review index](index.html) · [Shared direction](SHARED-DESIGN-SYSTEM.md). + +This is a source-backed review and design proposal. Production applications, live credentials, deployed data, browser keyboard behavior, and measured performance were not exercised. Mockups use illustrative data and demonstrate proposed patterns; they are not screenshots of the existing application. No production source was modified. + +## Summary + +3 P1, 4 P2, 1 P3 recommendations; no proven P0. Strong shared chrome, but mouse-only attribute actions, unmanaged modal focus and unnamed browse search warrant the first implementation pass. Numeric audit scores are withheld because runtime, load and assistive-technology checks were not performed. + +## Shared visual contract + +Keep IBM Plex Sans for reading and Plex Mono for identifiers, timestamps, and aligned values; warm paper, white panels, thin neutral rules, compact navigation, and one clear page heading. Use the shared Theme package for chrome and primitives. Shared means the same spacing, field, table, notice, focus, status, and responsive rules. Preserve explicitly permitted product accents. Do not fork a theme per page or introduce a separate dark dashboard. The mockups show accessible status ink and taller touch targets as proposals for the shared library, not new app-local token copies. + +## Verification and release gate + +At 1440 × 900, 1024 × 768, 390 × 844 and 200% zoom, verify that only intentional table regions scroll horizontally; headings, filters, notices and footer actions remain visible. Keyboard-test navigation, search, detail disclosure and all dialogs. Confirm text names and state announcements with a screen reader; measure text contrast (4.5:1) and non-text focus/control contrast (3:1). On coarse pointers, offer 44px targets without forcing every desktop data row to become tall. Test long tag paths, empty results, unavailable dependencies, stale snapshots, denied access and a slow operation that succeeds after several seconds. + +A source detector ran once across the gateway dashboard and ignitionoee router/registry component directories. It returned `[]`: see [gateways-detector.json](evidence/gateways-detector.json). This is a narrow mechanical result, not an accessibility pass; manual source findings below remain valid. CSS in separate host asset directories and Perspective JSON are outside that invocation. No detector false positives required dismissal. + +### MX-01 · P1 · Make the subscription workflow keyboard and touch accessible + +**Evidence:** [src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Shared/BrowseTreeNodeView.razor:69](/Users/dohertj2/Desktop/MxAccessGateway/src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Shared/BrowseTreeNodeView.razor:69). + +**Owner:** app interaction; shared tree/disclosure pattern. **Impact:** adding an attribute depends on double-click or right-click on a non-focusable `div`; the advertised primary workflow is unavailable to keyboard users. The node-name span is also click-only; its separate toggle button has a generic name and no expanded state. **Recommendation:** render an explicit “Watch attribute” button per attribute or selected-row action, use a named node button with `aria-expanded` and `aria-controls`, and retain context menus as an accelerator. **Acceptance:** Tab → node → expand → attribute → Watch completes without mouse; a touch user can watch a tag with one visible action. WCAG 2.1.1 / 4.1.2. **Command:** `$impeccable harden`. + +### MX-02 · P1 · Replace presentation-only modal overlays with managed dialogs + +**Evidence:** [src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Shared/ConfirmDialog.razor:4](/Users/dohertj2/Desktop/MxAccessGateway/src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Shared/ConfirmDialog.razor:4). + +**Owner:** shared dialog primitive plus app consumers. **Impact:** this component renders an `aria-modal` overlay without focus entry, focus containment, Escape handling or return focus. API-key creation repeats the pattern at `Pages/ApiKeysPage.razor:55`. The parent app links only shared nav-state JavaScript; the component itself contains no focus management. **Recommendation:** introduce a native dialog or a complete managed modal contract, preserve busy/cancel semantics, and use the same contract for confirmation and key creation. **Acceptance:** initial focus is deliberate; Tab stays within the dialog; Escape cancels when safe; focus returns to the invoking control; underlying writes cannot receive focus. WCAG 2.4.3 / 2.1.1. **Command:** `$impeccable harden`. + +### MX-03 · P1 · Give browse search a persistent accessible label + +**Evidence:** [src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/BrowsePage.razor:27](/Users/dohertj2/Desktop/MxAccessGateway/src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/BrowsePage.razor:27). + +**Owner:** app, following shared field contract. **Impact:** search has only a placeholder; its purpose disappears while typing and it has no explicit accessible name in markup. **Recommendation:** add a visible `label for`, input `id`, and search hint/result status association. **Acceptance:** the search is announced as “Filter Galaxy attributes”, the hint remains after entry, and a zero-result message includes Clear search. WCAG 3.3.2 / 4.1.2. **Command:** `$impeccable clarify`. + +### MX-04 · P2 · Turn the overview into an exception-first operating view + +**Evidence:** [src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/DashboardHome.razor:21](/Users/dohertj2/Desktop/MxAccessGateway/src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/DashboardHome.razor:21). + +**Owner:** app composition. **Impact:** eight equally weighted metrics followed by six Galaxy metrics make faults compete with uptime and lifetime totals. “View browse details” links to repository summary rather than live Browse. **Recommendation:** lead with a compact gateway/freshness strip and actionable faults, followed by sessions/workers/queue context. Put cumulative counters and repository size under a labeled disclosure; distinguish Repository status and Browse attributes destinations. **Acceptance:** from the first viewport, an operator can identify a fault and open the responsible session without reading every metric. Preserve every existing counter in the detail disclosure. **Command:** `$impeccable distill`. + +### MX-05 · P2 · Remove copied theme shades and local component styling + +**Evidence:** [src/ZB.MOM.WW.MxGateway.Server/wwwroot/css/site.css:134](/Users/dohertj2/Desktop/MxAccessGateway/src/ZB.MOM.WW.MxGateway.Server/wwwroot/css/site.css:134). + +**Owner:** Theme first, then local cleanup. **Evidence:** local zebra/hover fills at 134/144, button fills at 202–226, alert shades at 253–254, browse row fills at 324/340 and attribute flags at 398 repeat shared colors. **Impact:** a shared contrast or palette fix leaves these islands behind. **Recommendation:** replace literal neutral/status shades with existing tokens, move genuinely shared field/button/notice rules into Theme, retain browse geometry locally, and compare before deleting overlapping selectors. **Acceptance:** changes to shared hover/status tokens reach app tables, notices and tree flags; a local color scan permits only documented domain encodings. **Command:** `$impeccable extract`. + +### MX-06 · P2 · Expose complete errors without hover and announce recovery + +**Evidence:** [src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Shared/BrowseTreeNodeView.razor:48](/Users/dohertj2/Desktop/MxAccessGateway/src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Shared/BrowseTreeNodeView.razor:48). + +**Owner:** app + shared notice/detail pattern. **Impact:** tree-load failures are abbreviated with the full error available only in `title`; hover does not serve touch and screen-reader users reliably. Browse search/live-read errors at `BrowsePage.razor:43/125` also lack an explicit alert/status role. **Recommendation:** show a plain-language summary, Retry and expandable safe diagnostic detail; use one polite status for recovery and an alert for a user-triggered failure. **Acceptance:** a failed child load can be read and retried without collapsing the entire tree or losing subscriptions. No repetitive announcement on every 2-second refresh. **Command:** `$impeccable harden`. + +### MX-07 · P2 · Increase browse control hit areas without sacrificing data density + +**Evidence:** [src/ZB.MOM.WW.MxGateway.Server/wwwroot/css/site.css:344](/Users/dohertj2/Desktop/MxAccessGateway/src/ZB.MOM.WW.MxGateway.Server/wwwroot/css/site.css:344). + +**Owner:** shared control sizing + local tree geometry. **Impact:** the tree toggle is 1.1rem square; the subscription remove control is also compact. These are difficult targets on tablets used beside equipment. **Recommendation:** keep a compact visible chevron but expand its button hit area; apply the shared coarse-pointer rule consistently and make overflow local to tree/table regions. **Acceptance:** 44px coarse-pointer targets, readable wrapped metadata at 390px, no document-level horizontal scrolling, and a long tag does not hide the remove action. **Command:** `$impeccable adapt`. + +### MX-08 · P3 · Normalize heading and action language across the family + +**Evidence:** [src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Layout/MainLayout.razor:10](/Users/dohertj2/Desktop/MxAccessGateway/src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Layout/MainLayout.razor:10). + +**Owner:** shared terminology + app. **Impact:** the rail says Dashboard while the landing page says Overview, and sign-out capitalization differs between consumers. **Recommendation:** prefer Overview, API keys, Sign out, Refresh, and sentence case page titles throughout the family; keep runtime state strings intact where their exact value helps diagnostics. **Acceptance:** rail, document title and visible heading identify the same destination. Preserve stable nav keys. **Command:** `$impeccable clarify`. + +## What to keep + +- Shared chrome and `StatusBadge` domain-to-token adapter; do not move runtime state mapping into the UI library. +- Lazy child loading, capped search results and explicit no-cache/no-match states. +- Text labels inside status pills, scoped column headings, table scrolling, busy flags and confirmation for session management. +- Policy-aligned Alarms and Secrets navigation; API keys intentionally remain readable to Viewers. + +## Coverage and implementation order + +Deep inspection: Browse and recursive tree; shared confirmation/status components; Overview; API-key create markup; shell; host CSS. All remaining route markup was scanned for headers, data containers, feedback and action patterns. This does not assert every event handler or permission branch was executed. `/admin/secrets` is mounted from the common Secrets UI and is covered by the family shared-UI review. + +| Route | Source | Coverage | +| --- | --- | --- | +| `/alarms` | `src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/AlarmsPage.razor` | Source scanned | +| `/apikeys` | `src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/ApiKeysPage.razor` | Source scanned | +| `/browse` | `src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/BrowsePage.razor` | Source scanned | +| `/` | `src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/DashboardHome.razor` | Source scanned | +| `/events` | `src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/EventsPage.razor` | Source scanned | +| `/galaxy` | `src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/GalaxyPage.razor` | Source scanned | +| `/login` | `src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/Login.razor` | Source scanned | +| `/sessions/{SessionId}` | `src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/SessionDetailsPage.razor` | Source scanned | +| `/sessions` | `src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/SessionsPage.razor` | Source scanned | +| `/settings` | `src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/SettingsPage.razor` | Source scanned | +| `/workers` | `src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/WorkersPage.razor` | Source scanned | + +1. `$impeccable harden`: MX-01/02 and MX-06, then `$impeccable clarify`: MX-03. +2. `$impeccable extract` and `$impeccable adapt`: MX-05/07 after the shared release is available. +3. `$impeccable distill` / `$impeccable clarify`: MX-04/08. +4. `$impeccable polish` after interaction and responsive acceptance checks pass; rerun `$impeccable audit` on the running app. + +The mockup shows a proposed exception-first Overview, persistent state/freshness context, session detail disclosure and a functional local session filter. Restart, close-session and key operations are deliberately absent from this static artifact. + + +## Rendered proposal previews + +These are proposed UI artifacts with illustrative data, not screenshots of the current application. All use the same shared stylesheet. See [verification and limits](VERIFICATION.md). + +### MxAccessGateway + +[Interactive HTML](mockups/MxAccessGateway.html) · [Desktop PNG](evidence/MxAccessGateway-desktop.png) · [Mobile PNG](evidence/MxAccessGateway-mobile.png) + +![Proposed MxAccessGateway desktop UI](evidence/MxAccessGateway-desktop.png) + diff --git a/impeccable/OtOpcUa.md b/impeccable/OtOpcUa.md new file mode 100644 index 0000000..ff1489f --- /dev/null +++ b/impeccable/OtOpcUa.md @@ -0,0 +1,252 @@ +# OtOpcUa — Technical-Light UI recommendations + +Reviewed 2026-11-12. Mode: **Operate**. Source baseline: `412da27c5fb7e440e4a75d4f8e82e0e5b9832411` in `/Users/dohertj2/Desktop/OtOpcUa`. This is a source-backed audit and design proposal, not a claim of a live-browser usability or WCAG certification. + +[Review gallery](index.html) · [Fleet mockup](mockups/OtOpcUa.html) · [Raw workspace mockup](mockups/OtOpcUa-Raw.html) · [Detector evidence](evidence/OtOpcUa-detector.json) + +## Recommendation + +Keep the shared Technical-Light identity. OtOpcUa already delegates its shell to the common theme; its largest gaps are in the task surfaces inside that shell. Give operators a useful landing page, a clearly grouped rail, accessible trees and dialogs, a consistent page/table grammar, and readable failure details. Retain the Raw/UNS distinction and the fact that editing configuration does not deploy it. + +The mockups propose the same neutral paper, IBM Plex, restrained blue action accent, hairline tables and compact rail used by the family. Green, amber and red carry operational meaning, always accompanied by words. They introduce no alternate brand, dark theme or new product claims. + +## Scope and evidence + +The shipped web surface is `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI`, hosted by `src/Server/ZB.MOM.WW.OtOpcUa.Host`. `src/Client/...Client.UI` is an Avalonia desktop client and is outside this web review. The inspected `docs/images/connection-panel.png` depicts that desktop client; it is not a current web screenshot and was excluded as visual authority. No current web regression golden was identified. Runtime services and authenticated pages were not started or exercised. + +Package `ZB.MOM.WW.Theme` is centrally pinned at **0.5.0** in `Directory.Packages.props:244`. `Components/App.razor:16–23` loads Bootstrap, then `ThemeHead`, then the small local stylesheet and scoped styles. `Components/Layout/MainLayout.razor:15` uses `ThemeShell`; there is no hardcoded shell accent overriding future theme-level changes. The current theme source in scadaproj can be newer than this consumed package; validate the release actually consumed before removing any compatibility rule. + +Paths below are relative to `/Users/dohertj2/Desktop/OtOpcUa/`. For brevity, **UI** means `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/`. + +### Coverage inventory + +All 32 page files (31 routable components plus one development sample) were inventoried for route, policy, title/heading, table, state and component patterns. The 31 routable components declare **36 route templates**, because create/edit aliases share components; the machine inventory counts these templates separately. The development sample has no `@page` directive. Deep means markup and relevant behavior were read; scan means route/markup/state signatures were checked, with representative components reviewed. This is not a promise that every driver protocol's full runtime workflow was tested. + +| Surface | Routes / files | Depth and next validation | +|---|---|---| +| Shell, auth and account | `/`, `/login`, `/account`; `App`, `Routes`, main/login layouts | Deep. Check signed-in/out, long user names, policy-specific navigation, SSR login on a running host. | +| Fleet and runtime triage | `/fleet`, `/fleet/diagnostics`, `/hosts` | Deep. Verify polling failure, stale readings, large driver fleets and refresh/focus behavior live. | +| Raw authoring | `/raw`; `RawTree`, context menu, name/confirm/browse/import/tag dialogs | Deep tree, common dialogs and driver modal; scan specialized pickers. Preserve virtualization and lazy loading. | +| UNS authoring | `/uns`, `/uns/equipment/new`, `/uns/equipment/{EquipmentId}` | Deep tree and page/tabs; scan per-protocol tag editors, virtual-tag and alarm dialogs. Validate many references and long equipment paths. | +| Cluster management | `/clusters`, `/clusters/new`, `/clusters/{ClusterId}`, `/edit`, `/nodes/new`, `/nodes/{NodeId}` | Markup/state scan; representative creation/navigation patterns checked. Validate field errors and role-specific actions. | +| Cluster access and history | `/clusters/{ClusterId}/acls`, `/acls/new`, `/acls/{NodeAclId}`, `/audit`, `/redundancy` | ACL/audit/navigation deep; edit and redundancy scanned. Test grant scope, revoked principal hints and detailed failures. | +| Retired namespace routes | `/clusters/{ClusterId}/namespaces`, `/namespaces/new`, `/namespaces/{NamespaceId}` | Deep; compatibility notice retained, ordinary navigation should stop advertising retired work. | +| Deployment | `/deployments` | Deep markup, query and action feedback; test zero records, in-flight and degraded seal live. | +| Security and IDs | `/apikeys`, `/role-grants`, `/certificates`, `/reservations` | API-key/role/certificate/reservation markup and state scan; shared form/dialog findings apply. Keep one-time key reveal and UTC expiry semantics. | +| Scripting | `/scripts`, `/scripts/new`, `/scripts/{ScriptId}`, `/script-log` | Deep list/log and editor scaffold; Monaco bridge scanned. Test keyboard/editor fallback on the running host. | +| Operational events | `/alerts`, `/alarms-historian` | Deep markup/state scan; live connection, retained stale reading and bounded tail behavior inspected. | +| Shared secrets | `/admin/secrets` | Wrapper deep; shared Secrets.Ui internals reviewed separately in the family report. Preserve this host's per-page interactive boundary. | +| Driver families | Modbus, S7, AbCip, AbLegacy, TwinCAT, Focas, Heidenhain, OpcUaClient, Galaxy, Sql, Mqtt, MTConnect, Calculation; driver/device forms, address pickers, tag editors | Common modal/form dispatch deep; Modbus representative form deep; other family markup/pattern scan. Protocol correctness outside scope. | +| Development sample | `Dev/ContextMenuDemo.razor` | Scanned; no routable `@page` was present. Do not mistake this sample for a shipped navigation destination. | + +## Provisional audit score + +Scores summarize static evidence and do not imply measured live compliance. Performance is limited to implementation patterns, not latency or memory profiling. + +| Dimension | Score / 4 | Evidence | +|---|---:|---| +| Accessibility | 1 | Repeated unattached labels, glyph-only tree expanders, incomplete hand-rendered modal semantics. | +| Performance | 3 | Raw virtualization, lazy loading, capped/coalesced event tails, overlap-guarded polling and scalar deployment projections. Runtime budget unmeasured. | +| Responsive design | 2 | Shared responsive shell and many table wrappers; nowrap log toolbar and unwrapped deployment/equipment tables need correction. | +| Theming | 3 | Actual shared package adoption; local chip aliases and mixed Bootstrap/shared tables still diverge. Light-only is intentional, not a missing dark-mode defect. | +| Implementation integrity | 3 | Coherent operational product; home placeholder and retired namespace navigation weaken task continuity. Detector hits were vendor code only. | +| **Total** | **12/20** | **Significant targeted improvements; preserve the identity.** | + +### Detector interpretation + +The bundled detector was run once on the AdminUI source and emitted **14 warnings**, all under vendored `wwwroot/lib/bootstrap` or `wwwroot/lib/monaco`. Bootstrap caret border geometry, generic library collapse transitions, Monaco CSS-language examples and generated `` strings are not evidence of a broken OtOpcUa screen. They are recorded in the raw evidence, not promoted to product defects. No app-authored deterministic detector warnings appeared. The manually verified issues below are separate findings; a quiet detector does not establish accessible interactions. + +## Prioritized findings + +No P0 task-blocking defect was proven. Findings: **3 P1, 8 P2, 1 P3**. Shared token contrast and shared field-component semantics also apply, and are owned by the family theme report rather than counted again here. + +### OT-01 · P1 · Programmatically label forms and filters + +**Evidence:** `UI/Components/Shared/Drivers/DriverConfigModal.razor:28–30` renders the driver name label and input without association. `.../Drivers/Forms/ModbusDriverForm.razor:17–23` repeats this for Timeout and PLC family, and subsequent numeric fields follow the pattern. `UI/Components/Pages/ScriptLog.razor:16–25` has an unnamed select and a placeholder-only search field. `.../Pages/Uns/GlobalUns.razor:21–23` has a placeholder-only filter. Some fields already do this correctly, e.g. API key fields at `.../Pages/ApiKeys.razor:35–46`. + +**Impact:** Screen reader users cannot reliably determine the input purpose; placeholder text disappears while typing. WCAG 1.3.1 / 3.3.2 and, where no accessible name exists, 4.1.2. + +**Ownership:** Local instances; shared Theme should provide a robust field ID/hint/error association contract. + +**Recommendation:** Add stable unique `id`/`for`, visible filter labels, `aria-describedby` for help/errors and `aria-invalid` for invalid values. Prefer the enhanced shared field wrapper once available; do not assume visually adjacent text labels an input. + +**Acceptance:** Accessible-name inspection identifies every input/select by purpose across all protocol forms, including two instances of a reusable form. Clicking a label focuses its control; field errors remain linked after failed save. `$impeccable harden`. + +### OT-02 · P1 · Give every dialog one accessible focus lifecycle + +**Evidence:** `UI/Components/Shared/Raw/RawConfirmDialog.razor:8–30` and `.../Shared/Drivers/DriverConfigModal.razor:11–18` create visible Bootstrap-shaped divs using `display:block` and `role="dialog"`, without `aria-labelledby`, `aria-modal`, focus initialization/trap/return or Escape handling in their component code. The UNS inline delete at `UI/Components/Pages/Uns/GlobalUns.razor:76–105` repeats the pattern. Loading Bootstrap JS does not activate its modal manager for a div shown manually. + +**Impact:** Keyboard users can remain behind the modal, lose context or reach background controls while a destructive decision is visible. Potential WCAG 2.4.3 / 4.1.2 failures require runtime confirmation. + +**Ownership:** Shared visual/accessibility primitive in Theme, adopted locally; domain delete and validation behavior remain local. + +**Recommendation:** Standardize a dialog primitive with labelled title/description, modal background isolation, appropriate initial focus, Escape/close rules, focus containment and restoration. Preserve busy safeguards and validation content. Full driver configuration should graduate to a routed editor when users need prolonged work; keep short confirmation dialogs. + +**Acceptance:** Open by keyboard, cycle forward/backward, cancel, and reopen; background controls remain unreachable, focus returns to trigger, title is announced, errors preserve input, and confirmation focus defaults safely. Test with nested Monaco suggestions and narrow scrolling. `$impeccable harden`. + +### OT-03 · P1 · Name and expose tree expansion state + +**Evidence:** `UI/Components/Shared/Raw/RawTree.razor:210–216` and `.../Shared/Uns/UnsTree.razor:44–50` render triangle-only buttons without a node-specific accessible name or `aria-expanded`. The raw picker checkbox at `RawTree.razor:242–244` has no label association. + +**Impact:** Assistive technology announces ambiguous glyph controls and cannot discover which branch is expanded or which tag is selected. WCAG 4.1.2; picker naming also affects 1.3.1. + +**Ownership:** Local tree semantics with a shared expand-control visual pattern. Theme's `TreeTable` is a candidate pattern, not a drop-in replacement for the virtualized Raw tree. + +**Recommendation:** Give each toggle a node-specific name, accurate `aria-expanded` and appropriate controlled-region semantics; label every tag checkbox. Either implement a full keyboard tree pattern or retain semantic nested lists with real buttons; do not add `role="tree"` without its keyboard contract. Keep virtualization and lazy loading. + +**Acceptance:** A screen reader can identify the node and collapsed/expanded state, select a named tag, and recover from a lazy-load error. Focus survives a visible-row refresh and Show more. `$impeccable harden`. + +### OT-04 · P2 · Replace the placeholder entry page with task orientation + +**Evidence:** `UI/Components/Pages/Home.razor:6–7` is just “OtOpcUa Admin” and “Use the nav above…” although navigation is a side rail. + +**Impact:** Every operator starts with an empty page and must infer whether to check fleet, hosts or deployments. New users receive an inaccurate spatial instruction. + +**Ownership:** Local composition using shared page-header, notice, table and status components. + +**Recommendation:** Start with an operational overview of known fleet/deployment context and links to existing tasks; show time and source of data. Prefer an exception summary and compact fleet table over decorative metric tiles. Gate authoring actions to the user's policy. When no data is available, provide a precise next step such as open Fleet or create a cluster according to role. + +**Acceptance:** An operator can reach fleet diagnostics, a configuration author can reach Raw/UNS, and a deployer can inspect drift within one action; no unavailable or stale value appears healthy. The Fleet mockup illustrates the triage pattern, not an existing aggregate endpoint. `$impeccable onboard`. + +### OT-05 · P2 · Group navigation by task and honor page policies + +**Evidence:** `UI/Components/Layout/MainLayout.razor:17–40` puts 11 links into one Navigation section; Role grants and API keys are visible to roles their page policy rejects, while Secrets is policy-gated. The source itself documents that inconsistency at lines 33–37. `UI/Components/Shared/ClusterNav.razor:13` still advertises Namespaces; `.../Pages/Clusters/NamespaceEdit.razor:14–19` says it is retired in v3. + +**Impact:** High scan cost, advertised dead ends and misleading legacy authoring destinations. + +**Ownership:** Local navigation taxonomy, shared rail mechanics. Hiding a link supplements server authorization; it never replaces it. + +**Recommendation:** Use shared sections for Operations (overview/fleet/hosts/live), Configuration (clusters/Raw/UNS/reservations), Scripting, and Administration (keys/roles/certificates/secrets); keep Deployments close to configuration outcomes. Gate links with their actual policies. Remove Namespaces from ordinary tabs while retaining compatibility URLs with working Raw/UNS links. Use `ScrollNav` after validating the consumed Theme release supports it; handle long rails without hiding the session block. + +**Acceptance:** Operator, Designer and Administrator each see only meaningful destinations. Existing deep links remain explainable; active branch is evident; footer remains reachable on short screens. `$impeccable clarify`. + +### OT-06 · P2 · Unify page headings, document titles and table anatomy + +**Evidence:** `UI/Components/Pages/Deployments.razor:21,43–68` uses an h1 plus a bare Bootstrap striped table; Fleet uses h4 and `data-table` inside `table-wrap` at `.../Pages/Fleet.razor:21,67–108`. `.../Pages/Scripts.razor:29` and `.../Pages/Uns/EquipmentPage.razor:36–41` use other Bootstrap patterns. Fleet, Hosts and most admin pages do not set a page-specific `PageTitle`. + +**Impact:** Similar pages have different density and weight, and browser tabs do not consistently identify the current task. Heading levels express visual size rather than document structure. + +**Ownership:** Shared header/table grammar; local page adoption. + +**Recommendation:** One semantic h1 at a shared compact size, consistent description/actions placement, h2 for sections, a product-qualified page title, labelled tables with header scopes and accessible row actions. Put deployment/script/equipment tables in the same overflow region/chassis as fleet. Tables may have domain-specific columns; they should not have separate visual systems. + +**Acceptance:** All routes have one primary heading and a meaningful browser title. Keyboard and screen-reader users identify table purpose and action context. Side-by-side Fleet, Deployments and Scripts share typography, border, cell padding and action sizing. `$impeccable layout`. + +### OT-07 · P2 · Let filters wrap and keep touch targets usable + +**Evidence:** `UI/Components/Pages/ScriptLog.razor:13–30` puts title plus an unwrapped cluster of select, 200px input, connection pill and button on a single flex row. `.../Shared/Raw/RawTree.razor:213` uses an 18px-wide twist column (`wwwroot/css/site.css:47–49`) and zero padding. `.../Shared/ContextMenu.razor.css:21–22` fixes ellipsis controls at 1.75rem. + +**Impact:** The toolbar can overflow or compress unreadably; adjacent tree controls are difficult on touch. These source dimensions establish a risk, not a measured viewport failure. WCAG 1.4.10 and 2.5.8 require rendered checks; 44px is the family comfortable touch target, not the WCAG AA minimum. + +**Ownership:** Shared responsive toolbar/action spacing; local tree density. + +**Recommendation:** Use wrapping toolbar groups, flexible/min-width-zero fields and stacked small-screen headers. Keep horizontal scrolling inside labelled data regions. Enlarge interactive hit areas on coarse pointers, preserving compact desktop rows and virtualization height estimates; do not enlarge CSS row heights while retaining `ItemSize="30"` unchanged. + +**Acceptance:** At 390px and 200% zoom the document itself has no horizontal overflow; controls remain labelled and reachable. On coarse pointers primary controls have 44px targets. Test touch expansion with adjacent siblings. `$impeccable adapt`. + +### OT-08 · P2 · Make failure details available without hover + +**Evidence:** `UI/Components/Pages/Fleet.razor:103` abbreviates failure text at 80 characters into a title tooltip. `.../Pages/Deployments.razor:61` puts the degraded reason only in `title`. `.../Pages/ScriptLog.razor:73` abbreviates messages into title; `.../Pages/Clusters/ClusterAudit.razor:56–58` truncates details JSON into a single line with hover title. + +**Impact:** Touch and keyboard users cannot reliably read the reason or copy the complete diagnostic content. An operator may see “degraded” without a recovery path. + +**Ownership:** Shared row-detail disclosure presentation; domain content and diagnostics links local. + +**Recommendation:** Provide “View details” or expandable rows with full wrapping message, UTC timestamp, identity/correlation and copyable payload. Keep compact summaries in the table. Preserve the failure reason, and offer the existing diagnostics link where relevant. Long payloads should scroll within their own region. + +**Acceptance:** Full error and audit content is reachable by keyboard and touch without hover, remains readable with a 2,000-character message, and can be copied without truncation. `$impeccable harden`. + +### OT-09 · P2 · Distinguish accepted deployment from completed application + +**Evidence:** `UI/Components/Pages/Deployments.razor:133–141` marks `Accepted` as success and announces “dispatched”, then reloads once; the page has no subsequent timer. Initial `_deployments` is empty (`:84`), so loading and genuinely empty history render the same table. Domain code already distinguishes degraded sealed results at `:60–61`. + +**Impact:** Dispatch feedback is technically truthful but the UI does not help users follow the eventual apply/seal outcome; an empty-looking table can hide an in-flight initial read. + +**Ownership:** Local deployment workflow; shared busy/status/empty state pattern. + +**Recommendation:** Use explicit “Request accepted — deployment in progress” feedback, show the current request in a progress region, then refresh until a terminal state or offer a clear manual Refresh. Show initial loading, no deployments, rejected/no changes, dispatch error, applying, sealed and sealed-degraded distinctly. Preserve per-node apply semantics; never equate “sealed” with clean operation. + +**Acceptance:** A slow acceptance shows progress, a no-change response is informational, and a degraded terminal result exposes per-node reason and diagnostics without a browser reload. Polling stops/backs off appropriately and is disposed on navigation. `$impeccable harden`. + +### OT-10 · P2 · Clarify tree/filter scope and empty-state recovery + +**Evidence:** `UI/Components/Shared/Uns/UnsTree.razor:28–31` documents that the filter can only consider lazy tag children after loading. `.../Pages/Uns/GlobalUns.razor:21–23` calls it only “Filter by name”. Raw root errors at `.../Pages/Raw/GlobalRaw.razor:39–45` have no retry action; no-cluster states do not link to cluster creation. + +**Impact:** Users may read no matching loaded item as proof that a tag does not exist, or be stranded after a transient load error. + +**Ownership:** Local tree data behavior and recovery; shared filter/empty/error state visual grammar. + +**Recommendation:** Label “Filter loaded items” until server-side whole-tree search exists; explain exactly what is searched and distinguish no matches from no data. Provide Clear filter and retry actions. Link the no-cluster state to a policy-appropriate next step. A proposed global search must be separately implemented and must not imply unloaded-tree coverage today. + +**Acceptance:** Match count and scope are visible, Clear restores context, load error can be retried, and no-data text does not claim absence of unloaded records. `$impeccable clarify`. + +### OT-11 · P2 · Standardize event-tail control and stale-data communication + +**Evidence:** `UI/Components/Pages/Alerts.razor:22–30` and `.../Pages/ScriptLog.razor:26–29` expose live/disconnected and Clear, but no pause reading control. Fleet shows last refresh (`.../Pages/Fleet.razor:29–30`) while failures outside cancellation can escape to its error boundary; Alarms historian already preserves last status plus read time when unavailable (`.../Pages/AlarmsHistorian.razor:36–40`). + +**Impact:** Incoming rows can move the content being read. Users need to distinguish disconnected transport, old retained information and a healthy empty window. + +**Ownership:** Shared freshness/live-status pattern; local subscription and retention semantics. + +**Recommendation:** Replicate the historian's honest stale-read behavior where feasible. Add a clearly labelled Pause updates/Resume control to live tails and define retention while paused. Announce connection/error summaries through a polite region rather than announcing every event row. Rename Clear to “Clear visible log” or equivalent so it cannot imply deleting historian records. + +**Acceptance:** Reading can be paused without losing scroll/focus, Resume reconciles to the bounded tail, disconnected differs from zero events, and stale data shows last successful read. Stress-check the capped/coalesced buffer rather than replacing it with unbounded accumulation. `$impeccable harden`. + +### OT-12 · P3 · Normalize technical iconography and status aliases + +**Evidence:** `UI/Components/Shared/Raw/RawTree.razor:259–268` maps kinds to platform emoji; `.../Shared/Uns/UnsTree.razor:99` embeds a gear glyph in a link. `UI/wwwroot/css/site.css:24–25` maintains chip aliases alongside Theme's status variants. `.../Shared/ToastNotification.razor:15` has an unlabelled dismiss button; include that naming fix in OT-01 rather than treating it as decorative polish. + +**Impact:** Emoji shape, color and alignment vary by OS, unlike the disciplined shared chrome. Aliases increase drift risk. + +**Ownership:** Shared icon/control naming conventions, local migration. + +**Recommendation:** Use one family icon set or simple shared SVG controls, hide decorative icons, and retain visible text. Converge local alias call sites on shared semantic variants after checking visual contrast in the theme release consumed. Do not invent alternate meaning for caution vs warning. + +**Acceptance:** Same object/action has the same icon/stroke across sisters; no emoji substitutes for accessible state text; chips use canonical semantic variants. `$impeccable polish`. + +## What to retain + +- Genuine use of `ThemeHead`, `ThemeShell`, `ThemeScripts` and `LoginCard`; vendored fonts/Bootstrap/Monaco support disconnected industrial environments. Do not introduce CDN dependencies. +- Static SSR login with antiforgery token, deliberate per-page interactive boundaries and the `/admin/secrets` wrapper. A global interactive-router conversion would change behavior, not merely style. +- Raw `Virtualize` (`RawTree.razor:30`), lazy child loading, capped Show more and menu caching. Accessibility work should preserve their scale advantages. +- Fleet polling overlap guard, cancellation and disposal (`Fleet.razor:121–131,143–150`); the UI should build on these rather than launch new overlapping queries. +- Explicit sealed-degraded/applied-degraded semantics. Healthy-looking color must not erase partial address-space failures. +- Alarms historian availability distinctions, a retained last reading and its timestamp. This is a good pattern for the family. +- Scalar-only deployment projections and a 50-row limit (`Deployments.razor:98–110`); bounded 500-entry, coalesced script log rather than per-event unbounded rerendering. + +## Mockup reading guide + +**Fleet triage** keeps the known fleet fields, replaces aggregate tiles with a compact status summary and filters, and adds an expandable full failure explanation. The proposed rail groups existing routes; the local mockup filter searches only its illustrative rows. A Read details disclosure demonstrates keyboard/touch access without pretending to fetch a real snapshot. + +**Raw workspace** keeps Enterprise → Cluster → Folder → Driver → Device → TagGroup → Tag and distinguishes authoring from deployment. It demonstrates a visible selected device path and a companion inspector with grouped connection information, while retaining native hierarchy disclosures. Its static selection is illustrative; it is not a working configuration editor. This is a proposed way to reduce context-menu discovery load, not an assertion that Raw currently has live tag values or a new search endpoint. + +Both mockups use the exact same shared mockup stylesheet as the other family examples. Values, node names, revisions and times are illustrative. Only local navigation, disclosures and explicitly described sample filtering work; no mock control modifies a fleet. + +## Rollout and acceptance plan + +1. **Shared theme first:** settle contrast, field associations, page header, labelled status/freshness, responsive toolbar, dialog contract and row details with the family recommendations. Publish one reviewed compatible release; do not copy its CSS into each app. +2. **P1 local adoption:** label all protocol/device/tag fields and filters, fix dialog lifecycle, and name tree expanders/pickers. Validate keyboard and screen reader flows on one representative protocol, then verify every form family using a field/interaction inventory. +3. **Operational consistency:** apply page/table grammar to Fleet → Hosts → Diagnostics → Deployments → Alerts/Script log, then the remaining admin tables. Introduce deployment progress and readable error details with honest stale/empty states. +4. **Navigation and authoring:** replace placeholder home, gate/group rail links, remove retired Namespace tabs, then trial the Raw inspector with expert users. Keep existing URLs and wire contracts stable. +5. **Bounded review:** desktop 1440px, compact 1024px, mobile 390px, 200% zoom; keyboard-only and a screen reader; long node names, 2,000-character errors, no rows, filtered empty, initial loading, request rejection, disconnected/stale, and least-privilege roles. Include big Raw branches and rapid navigation during polling to catch performance/focus regressions. +6. Run `$impeccable audit` after implementation and `$impeccable polish` last. Compare the same Fleet and authoring scenarios against the other family screens before accepting release. + +Recommendations are review artifacts only. No production OtOpcUa files were changed, no app was deployed, and source-only scores must be revised when runtime evidence is available. + + +## Rendered proposal previews + +These are proposed UI artifacts with illustrative data, not screenshots of the current application. All use the same shared stylesheet. See [verification and limits](VERIFICATION.md). + +### OtOpcUa + +[Interactive HTML](mockups/OtOpcUa.html) · [Desktop PNG](evidence/OtOpcUa-desktop.png) · [Mobile PNG](evidence/OtOpcUa-mobile.png) + +![Proposed OtOpcUa desktop UI](evidence/OtOpcUa-desktop.png) + +### OtOpcUa-Raw + +[Interactive HTML](mockups/OtOpcUa-Raw.html) · [Desktop PNG](evidence/OtOpcUa-Raw-desktop.png) · [Mobile PNG](evidence/OtOpcUa-Raw-mobile.png) + +![Proposed OtOpcUa-Raw desktop UI](evidence/OtOpcUa-Raw-desktop.png) + diff --git a/impeccable/Overview.md b/impeccable/Overview.md new file mode 100644 index 0000000..34f4823 --- /dev/null +++ b/impeccable/Overview.md @@ -0,0 +1,106 @@ +# ZB.MOM.WW.Overview — fleet visibility + +Reviewed November 12, 2026. Mode: Operate. [Mockup](mockups/Overview.html) · [Shared contract](SHARED-DESIGN-SYSTEM.md). + +## Scope and current identity + +Deeply inspected the single `/` page, `InstanceCard`, `MainLayout`, `App`, and `wwwroot/css/site.css`. Scanned the snapshot/poller boundary and existing dashboard mockup. These cover the application’s complete page/component surface; the [inventory](evidence/source-inventory.json) records the checkout. Source pins Theme **0.5.0** (`src/ZB.MOM.WW.Overview/ZB.MOM.WW.Overview.csproj:28`). Preserve its existing purple accent (`MainLayout.razor:9`), anonymous read-only operation, app/group hierarchy and distinct ready/active/leader signals. + +Paths below are relative to `ZB.MOM.WW.Overview/src/ZB.MOM.WW.Overview/`. This is source inspection; the current deployed dashboard was not browser-tested. The HTML concept is independently rendered review artwork. + +## Findings + +### OV-01 · P1 · Stale information becomes harder to read precisely when needed + +**Evidence:** `wwwroot/css/site.css:57–58` lowers instance body and host opacity to 0.55; `:65–67`, `:75`, and `:79–82` use small faint text. Shared DS-01 already measures faint ink below 4.5:1 before dimming. + +**Impact:** operators investigating stale nodes lose readable last-known values and host identity. + +**Recommendation:** adopt shared accessible ink tokens; keep stale values fully opaque and mark freshness explicitly with “Stale · last successful response …” and a neutral surface treatment. Separate freshness from last known health. + +**Ownership / acceptance:** Theme for token fixes, Overview for opacity/state presentation. Read host/error/freshness at 200% zoom, verify computed contrast, and confirm stale still reads as stale when color is unavailable. Suggested commands: colorize, harden. + +### OV-02 · P1 · Individual check state relies on a colored square + +**Evidence:** `Components/Widgets/InstanceCard.razor:79–82` renders dot class, check name and freeform description without the entry's actual status text. A description need not repeat its state. + +**Impact:** color-independent and screen-reader inspection cannot reliably distinguish a healthy/degraded/unhealthy check from markup alone. + +**Recommendation:** include explicit per-check status text, with decorative dot hidden from assistive technology. Keep the real check description; do not replace it with generic healthy copy. + +**Acceptance:** keyboard/screen-reader users can name each check's status without interpreting a color or inferring from description. Owner: Overview. Suggested commands: harden, clarify. + +### OV-03 · P2 · Pause and connection language imply the wrong state + +**Evidence:** `Components/Pages/Overview.razor:26–31` maps `_paused` to a disconnected connection pill; `:140–151` deliberately stops adopting snapshots while the backend poller continues. No toggle pressed state is supplied. + +**Impact:** a paused view can look like a network outage; operators cannot immediately tell whether collection or only their display is paused. + +**Recommendation:** say “View paused — background polling continues,” retain snapshot age, use neutral rather than failure styling, expose the button's toggle state. Announce pause/resume once in a polite status region, not every five-second tick. + +**Acceptance:** pause freezes adopted values, timestamps keep aging, resume adopts latest snapshot, and announcements clearly describe display behavior. Owner: Overview. Suggested commands: clarify, harden. + +### OV-04 · P2 · Group summary combines stale and unreachable under one label + +**Evidence:** `Components/Pages/Overview.razor:207–212` counts either `Unreachable` or stale as `missing`, then labels that total “unreachable.” + +**Impact:** a healthy last-known node whose view is paused can be reported as unreachable at group level, even though freshness and network state are different signals. + +**Recommendation:** show separate counts for unreachable and stale, and label overlaps clearly; application rollups should communicate whether their data is stale even if the stored worst status was healthy. + +**Acceptance:** paused healthy sample, fresh unreachable sample, stale unreachable sample and mixed group each produce truthful distinct labels without double-counting an overall affected total. Owner: Overview. Suggested commands: clarify, harden. + +### OV-05 · P2 · Full error evidence is hidden in a hover title + +**Evidence:** `Components/Widgets/InstanceCard.razor:65–69` truncates error text to 48 characters and exposes the remainder only through `title`. Check names have `min-width:9.5rem` in flex rows (`site.css:89–92`); descriptions have no explicit narrow-screen stacking rule. + +**Impact:** touch/keyboard users cannot reliably read the complete diagnostic cause; long names/descriptions can crowd narrow cards. + +**Recommendation:** put full error evidence in a native disclosure with wrapping text. Stack check name, text status and description on narrow cards. Avoid putting a tooltip in the critical recovery path. + +**Acceptance:** 390px viewport, 200% zoom and long diagnostic text remain readable; no document-level overflow; disclosures work by keyboard. Owner: Overview. Suggested commands: adapt, harden. + +### OV-06 · P2 · Fleet scale needs an optional exception-focused view + +**Evidence:** `Components/Pages/Overview.razor:46–120` renders six aggregate cards and every application/group/instance, with no filter or compact triage view. `:178–182` shows server-local time without a zone label. + +**Impact:** larger fleets require scanning healthy instances to find problems; users on a different zone may misinterpret “last sweep.” This is a scale recommendation, not a measured performance defect. + +**Recommendation:** retain the full fleet default and offer a labeled “Needs attention” filter, with separate state/freshness columns or a compact list. Keep native check details and raw ready/active evidence. Label the actual zone or use explicit UTC. The mockup illustrates the optional list view; do not remove useful topology cards without validation. + +**Acceptance:** clearing filters always restores the full fleet; absent values read Unknown/Pending, not zero/healthy; changing views preserves group identity and leader/active distinctions. Owner: Overview. Suggested commands: layout, clarify. + +## Preserve + +- Snapshot-driven rendering; pages never probe independently and a local tick keeps freshness aging. +- Stale is treated as distinct from a fresh sample; pause does not stop collection. +- Active and Akka leader remain separate, with raw cluster evidence available. +- MXAccess session counts differ from Historian warm pool depth; a zero warm pool is normal. +- Anonymous and read-only is an explicit requirement. Add no login or mutation controls. +- External management links already use `rel="noopener"`. + +## Delivery and validation + +1. DS-01, OV-01/02: readable stale values and textual check state. +2. OV-03/04/05: truthful pause/rollup language and accessible diagnostics. +3. OV-06: optional triage view, time-zone labeling, and supported-package adoption. + +Verify initial pending, empty/not-yet-polled, healthy, degraded, down, unreachable, stale, split-leader evidence, pause/resume, long host names and large fleet behavior. Preserve independent per-target publishing. Measure render cost with realistic fleet size before adding virtualization. Run Impeccable audit and polish after implementation. Runtime accessibility/performance conformance remains unverified. + +## Independent verification + +A second source review checked the complete page/widget markup, the snapshot publication contract, pause/adoption behavior, status/freshness derivation, local CSS, and shared-theme consumption. The six findings are supported by source; no live/runtime result is implied. The snapshot remains immutable per published graph, and remote cluster evidence is HTML-escaped before the deliberate `MarkupString`; preserve both protections. + +The combined [source detector run](evidence/shared-surfaces-detector.json) covered Overview, Secrets UI and Theme once. Its four findings all point to Overview's vendored Bootstrap CSS: generic caret border geometry and collapse width/height transitions. These are library definitions, not evidence of a failing displayed dashboard. No app-authored deterministic warning was emitted; manually verified findings above remain actionable. + + +## Rendered proposal previews + +These are proposed UI artifacts with illustrative data, not screenshots of the current application. All use the same shared stylesheet. See [verification and limits](VERIFICATION.md). + +### Overview + +[Interactive HTML](mockups/Overview.html) · [Desktop PNG](evidence/Overview-desktop.png) · [Mobile PNG](evidence/Overview-mobile.png) + +![Proposed Overview desktop UI](evidence/Overview-desktop.png) + diff --git a/impeccable/README.md b/impeccable/README.md new file mode 100644 index 0000000..7d8fdcb --- /dev/null +++ b/impeccable/README.md @@ -0,0 +1,55 @@ +# Impeccable review of the SCADA web UI family + +November 12, 2026. Recommendations and mockups only; production applications were not edited. + +**Start with [the visual review index](index.html)**, then read [the shared design contract](SHARED-DESIGN-SYSTEM.md). The priority is one Technical-Light family: IBM Plex, warm surfaces, restrained product accents, consistent labels/actions/statuses, and accessible behavior. The proposed mockups refine the existing identity. + +## Project deliverables + +| Project report | Main mockup focus | Open HTML concepts | +|---|---|---| +| [OtOpcUa](OtOpcUa.md) | Fleet triage and Raw device workspace | [OtOpcUa](mockups/OtOpcUa.html) · [OtOpcUa-Raw](mockups/OtOpcUa-Raw.html) | +| [MxAccessGateway](MxAccessGateway.md) | Faulted-session triage and repository context | [MxAccessGateway](mockups/MxAccessGateway.html) | +| [ScadaBridge](ScadaBridge.md) | Topology freshness and audit investigation | [ScadaBridge](mockups/ScadaBridge.html) · [ScadaBridge-Audit](mockups/ScadaBridge-Audit.html) | +| [HistorianGateway](HistorianGateway.md) | Read history console and write separation | [HistorianGateway](mockups/HistorianGateway.html) | +| [BTDB](BTDB.md) | Batch editing with clear validation and context | [BTDB](mockups/BTDB.html) | +| [ignitionoee](ignitionoee.md) | Router jobs, registry eligibility and native operator view | [ignitionoee](mockups/ignitionoee.html) · [ignitionoee-Registry](mockups/ignitionoee-Registry.html) · [ignitionoee-Perspective](mockups/ignitionoee-Perspective.html) | +| [Overview](Overview.md) | Read-only fleet status and freshness | [Overview](mockups/Overview.html) | +| [Secrets](Secrets.md) | Metadata and target-aware secret rotation | [Secrets](mockups/Secrets.html) | +| [Theme](Theme.md) | Common status, fields and interaction language | [Theme](mockups/Theme.html) | + +Every report includes source evidence, prioritized findings, ownership, acceptance checks, coverage and limitations. Shared findings are defined once in the shared contract rather than counted again as independent defects in every application. Multiple mockups illustrate major workflows; they do not represent every audited route. + +## Detailed implementation plan + +[Implementation plan](IMPLEMENTATION-PLAN.md): standardize all seven existing bUnit projects on 2.7.2 first, then implement the shared theme and sister UI updates. Includes per-project chapters, dependency gates, regression checks, rollout and rollback. + +## First implementation priorities + +1. Shared Theme: readable status/secondary inks, associated labels/errors, complete accent states, focus/busy/reduced-motion behavior. +2. Shared Secrets UI: isolate draft state when switching target secrets; give delete confirmations a full modal focus lifecycle. +3. App P1 findings: keyboard-accessible row/tree workflows, named fields/dialogs, truthful failed/unknown states and unambiguous time-zone handling. +4. Apply shared filter/table/detail patterns, responsive structure, and role-aware navigation locally while retaining each project's domain behavior. +5. Release the reviewed shared version, migrate consumers, then validate real routes and finish with Impeccable audit and polish. + +See project reports for the local priorities and exact locations. No proven P0 is asserted from the source scan. A prioritization label is a recommendation, not a filed issue or a release authorization. + +## Scope and review method + +The user requested subagents. Three specialist agents reviewed the sister repositories in parallel; a second assignment covered BTDB and an independent pass checked Overview, Secrets and Theme. The parent established the shared contract, measured token contrast, reconciled coverage, and built/verified the artifact collection. Impeccable's installed 4.3.1 skill, audit guidance, Operate guidance and craft floor informed the work. This is a coordinated source audit and design recommendation exercise, not the formal `critique` command or a scored live accessibility assessment. + +Active checkouts reviewed: `OtOpcUa`, `MxAccessGateway`, `ScadaBridge`, `HistorianGateway`, `BTDB`, `ignitionoee`, and hosted `ZB.MOM.WW.Overview`, `ZB.MOM.WW.Secrets.Ui` and `ZB.MOM.WW.Theme`. ignitionoee includes router, registry and Perspective operator views. Hidden worktrees, duplicate checkouts and generated/vendor code were excluded from the active route inventory. Detector invocations may have traversed vendored assets; reports identify those warnings rather than treating them as application findings. + +Other hosted libraries (Auth, Audit, Health, Configuration, LocalDb, Telemetry, GalaxyRepository and SPHistorianClient) have no standalone authored web UI in this checkout. Shared Auth login rendering and domain audit/health consumers are included in the relevant reports. Database/CLI utilities, historical design-only siblings, unrelated Desktop directories, Bootstrap/Monaco implementations and generated outputs are not separate web projects in this review. + +[Source inventory](evidence/source-inventory.json) records checkout HEADs, active route templates and source paths. Discovery counts include aliases; project reports distinguish route templates, routable components and support files. Route discovery is broader than deep manual inspection. Reports mark which families received deep inspection and which were scanned. Current source outranks old adoption docs and stale screenshot fixtures. A package pin in source does not establish a deployed version. + +## Mockups and verification + +There are **13 responsive HTML concepts** for **9 project/library reports**, all using [shared.css](mockups/shared.css) and local Plex fonts. Product-specific colors remain intentional: Historian green, BTDB teal and Overview purple. Perspective uses a native operator-oriented composition; the HTML is a visual specification for Ignition view/style resources, not a claim that the Blazor package runs there. + +Mockups contain synthetic data, local filters/disclosures/previews and clear proposed-state labels. They send no SCADA queries or mutations. Controls representing production writes are explanatory, disabled or local demonstrations. + +Each concept has full-page desktop and mobile PNGs in `evidence/`, linked in the visual index. [Verification record](VERIFICATION.md) describes the bounded browser checks and their limits. [Contrast evidence](evidence/contrast.json) contains current and proposed pair calculations. Source detector JSON is retained alongside reports. No mockup result proves production accessibility, backend behavior, production performance, or native Perspective runtime acceptance. + +Open `index.html` in a browser; no package installation, build or server is needed. Keep the folder intact so its relative HTML/CSS/font/image links work. diff --git a/impeccable/SHARED-DESIGN-SYSTEM.md b/impeccable/SHARED-DESIGN-SYSTEM.md new file mode 100644 index 0000000..0679ab5 --- /dev/null +++ b/impeccable/SHARED-DESIGN-SYSTEM.md @@ -0,0 +1,94 @@ +# One Technical-Light family + +Review date: November 12, 2026. Mode: Operate. This is a recommendation package and a set of proposed visual artifacts, not an implementation or a production acceptance report. + +## Direction + +Keep the established visual identity: IBM Plex Sans, IBM Plex Mono for identifiers and measurements, warm paper, white working surfaces, fine neutral rules, compact rectangular status chips, a 220px desktop rail, and restrained product accents. Improve the system once, then apply it consistently. Do not give each project a new layout, font, card treatment, or status palette. + +The current source in `ZB.MOM.WW.Theme` is the visual authority. Its `Directory.Build.props:7` declares 0.5.3. Consumer versions differ; a version declared in a checkout is not evidence of what is deployed. The old `components/ui-theme/README.md` “not started” matrix and the shared-contract document's 0.2.0 description are historical evidence, not the present adoption state. + +## Common contract + +| Element | Family rule | Allowed local variation | +|---|---|---| +| Shell | ThemeShell, one main landmark, a persistent current location, native mobile nav disclosure | Product name, role-aware route groups, optional pinned session footer | +| Accent | Existing approved product accent; supply matching deep/hover/focus/tint tokens | Preserve Historian green, Overview purple, and any source-verified product accent; no per-page palette | +| Typography | Plex Sans; 14–15px working text; 24–26px page heading in proposals; 18px section heading; mono only for data | Domain code/editor font and data density | +| Surfaces | Paper `#f4f4f1`, card white, neutral border; existing 8px panel radius | Specialized topology/editor canvas | +| Spacing | 4, 8, 12, 16, 24, 32px; close related controls, separate tasks | Dense desktop tables can use smaller row padding with adequate targets | +| Page header | One h1, short scope/context, freshness where relevant, one primary action | Read-only surfaces need no primary action | +| Actions | Shared primary, secondary, danger, ghost treatments; explicit busy/disabled/error states | Domain command names and policy rules | +| Data | Labeled filters above data, scoped scrolling, real headers, sort state, stable identity | Tree/table/editor presentation appropriate to task | +| Forms | Programmatic label, hint/error association, required state, field-local recovery | Protocol-specific editors remain local | +| Status | One semantic palette plus plain state text; separate quality, role, transport, freshness | Domain vocabulary stays accurate: pooled ≠ in use, active ≠ leader, disabled ≠ failed | +| Time | Explicit zone and timestamp semantics, relative age plus exact time where useful | UTC export, local operational display, or an explicit zone selector | +| Dialogs | Accessible name, initial focus, modal isolation, Escape/cancel where safe, focus return | Domain-specific confirmation text and authorization | +| Responsive | Rail collapses below 992px; content remains visible; details stack; wide grids scroll inside their container | A complex desktop editor may offer a clearly scoped mobile summary | +| Touch | Aim for 44px touch actions; retain efficient desktop density | 24px minimum target/spacing rule must be assessed separately from the 44px design target | +| Motion | Useful state feedback; no repeating entrance choreography; reduced-motion alternatives | No requirement to add motion to operational screens | + +All mockups share [one stylesheet](mockups/shared.css) and vendored Plex assets. Proposed darkened status inks are intentionally shown in every concept. They are candidates for new semantic foreground tokens, not instructions to repurpose every existing dot/chart token. Mockups simplify domain data to make the recommended hierarchy reviewable. New filters, detail panes, and state selectors are explicitly proposals; they are not claims about existing functionality. + +## Shared findings and implementation recommendations + +### DS-01 · P1 · Small status and supporting text need accessible foreground tokens + +**Evidence:** `ZB.MOM.WW.Theme/src/ZB.MOM.WW.Theme/wwwroot/css/theme.css:45`, `:54–57`, `:76`, `:187–200`, `:210–215`. Existing small chip text pairs measure 3.09:1 (OK), 3.74:1 (warning), 3.89:1 (bad), 2.91:1 (idle). Faint ink is 3.21:1 on white and 2.92:1 on paper. These ordinary small text treatments fall below a 4.5:1 target. See [reproducible pair calculations](evidence/contrast.json). This is a token-pair calculation; runtime overlays, opacity, and app overrides need separate verification. + +**Impact:** table labels, state chips, host names, and freshness metadata become difficult to read, especially on industrial displays and stale/dimmed content. + +**Recommendation:** add dedicated status text tokens, preserving brighter colors for dots where appropriate. Proposed foregrounds: OK `#236f34`, warning `#855000`, bad `#b42121`, idle `#535d66`; secondary/faint text `#626970`. On existing matching backgrounds these measure 5.55, 5.98, 5.69, 5.88, and at least 5.05 respectively. Audit green/purple accents independently. Keep textual status distinctions. + +**Acceptance:** every actual small-text foreground/background pair reaches 4.5:1 in both supported schemes and all states; focused control boundaries remain visible; no stale-state opacity reduces essential text below target. Owner: Theme first, then consumer exceptions. Suggested Impeccable commands: colorize, audit. + +### DS-02 · P1 · TechField does not connect labels or errors to its control + +**Evidence:** `Components/TechField.razor:3–7` renders a sibling `