Files
scadaproj/impeccable/BTDB.md
T

20 KiB
Raw Blame History

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 · Suite index · Shared direction

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

  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.

BTDB

Interactive HTML · Desktop PNG · Mobile PNG

Proposed BTDB desktop UI