164 lines
20 KiB
Markdown
164 lines
20 KiB
Markdown
# 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)
|
||
|
||

|