feat(ui): refine global shell utilities

2026-09-28 18:19:27 +02:00
parent 8e56ceabf5
commit 0f54007015
18 changed files with 322 additions and 63 deletions
@@ -11,7 +11,8 @@ Reconciled against [P4-06](../phase-4/p4-06/README.md#opendeferred-issue-reconci
 | P4-04-O01 toast covers bottom action | Addressed in P5-00: bottom feedback clearance, native success toast tested while open | Feedback gate ready for the defined Connections action; not a universal overlay manager or company-modal error repair |
 | P5-00-D01 fixed worker data with system clock | **Closed 2026-09-21**: test now injects its existing fixed clock; complete backend rerun 916/916 | P5-01 baseline gate satisfied; production worker unchanged, no skip/expected annotation |
 | P5-00-D02 browser Back loses Jobs row focus | **Open** existing route behavior exposed by waiting for the actual workspace before Back; all four locale/theme cases. Explicit workspace Back passes `focusJobId` and remains protected | **Blocks affected P5-03/08 navigation accessibility acceptance**, not unchanged shell. Browser query and local-density reset plus explicit-button focus have separate oracles; no route/table application fix in P5-00 |
-| P3-O02 command error→empty / late query results | Source-confirmed search catches; explicit failure/pending isolation needs owner tests | **Blocks later slice P5-02 acceptance**; retain existing simple commands in 01, no expanded command redesign in 00 |
+| P3-O02 command error→empty / late query results | **Addressed in P5-02**: failed search has Retry, aborted/late results are discarded after a newer query or close; focused and real-browser regressions pass | Search-state gate closed locally; manual screen-reader acceptance is separately open below |
+| P5-02-D01 utility screen-reader operation | Automated axe and keyboard checks pass, but no human screen-reader command/notification task has been recorded | **Blocks P5-02 accessibility acceptance and automatic P5-03 progression** under the approved P5-02 plan. Operator steps and evidence request are in [P5-02](p5-02/README.md) |
 | P3-O02 workspace search replacement loses `followMode` | Source-confirmed `setParams({section})` | **Blocks later slice P5-08b** adapter migration until retained-query proof |
 | P4-02-D03 mobile progress scroll not focusable | Open loaded axe finding | **Blocks P5-08a affected Overview migration**, not shell; targeted G-WORKSPACE proof |
 | P4-02-D04 literal AI context `{name}` | Open both locales | **Blocks P5-08b affected application AI labels**; correct interpolation without changing context/API |
@@ -1,6 +1,6 @@
 # Phase 5 — Representative screens / major UI redesign plan

-**Completed successor: [P5-01 AppShell and grouped navigation](p5-01/README.md).** The first major visible redesign groups every existing destination without changing the 31-pattern route/provider contract. Its inherited backend prerequisite repair established **918/918**, and the P5-01 shell route/focus/accessibility contract is protected. P5-02 and B07 have not started. F04 remains open.
+**Current successor: [P5-02 Global shell utilities](p5-02/README.md), implementation verified with conditional accessibility acceptance.** The first major visible redesign, P5-01, grouped existing destinations without changing the 31-pattern route/provider contract. P5-02 retains existing commands and notifications while fixing search error/stale-result semantics. A manual screen-reader utility task is still required before automatic P5-03 progression. B07 has not started; F04 remains open.

 Historical planning checkpoint: source `2a2f9e48052c562ef599825458d0d3a6f9f9fc61`, inspected on 2026-09-13 on `codex/ui-redesign-phase4`. That checkpoint was documentation-only; the successor record above owns implementation/validation status.

@@ -0,0 +1,49 @@
+# P5-02 — Global shell utilities
+
+Source: [approved Phase 5 plan](../PHASE5_PLAN.md#p5-02--global-shell-utilities). This checkpoint follows P5-01 `8e56cea`; no route, provider, storage, backend contract, notification producer or command catalogue was added. F04 and P2-D01 remain open. P5-03 and B07 have not started.
+
+## Result and preservation
+
+The six existing commands and existing job/company results now appear in labelled Actions and pages, Jobs and Companies groups. Search retains the owned API client and 250 ms debounce. One aborted request pair per query prevents old results from replacing newer results or appearing after the dialog closes/account changes. A failed request shows a Retry alert; it is never represented as an empty result. The existing no-match state appears only after successful search. Arrow Up/Down, Home/End and Enter work from the search field and result buttons; IME composition is ignored. Ordinary Tab, Escape, initial focus and MUI focus return remain intact. The result announcer changes after the debounced search settles rather than on every keystroke.
+
+The existing bell retains the same recent-notification endpoint, read/dismiss mutations and `/operations` link. Loads are cancelled when closed or replaced, private items clear on close, and late mutation completions cannot update the next panel generation. Unread items now have a text label independent of their selected surface colour. A load error keeps its Retry action and does not show an empty inbox. Opening a notification still marks it read where needed; it does not complete a task.
+
+| PRES contract | Existing behavior retained | P5-02 change | Evidence |
+|---|---|---|---|
+| PRES-E07 | Six actions/pages, exact job/company destinations, keyboard trigger, reviewed Add Job | Group and keyboard navigation; distinguish loading/error/empty | `quick-command-preservation.test.tsx`; real-App four-locale/theme utility journeys and existing command/dirty-navigation browser cases |
+| PRES-E08 | EN/Bokmål, light/dark, dialog/feedback and focus | Localized groups/status and inherited semantic focus/colour | Type/lint/browser scans; four-mode screenshots and keyboard review |
+| PRES-E09 | Authenticated session isolation and private-tree disposal | Abort/ignore stale command and bell responses | Deferred-response tests; existing B02/session suite and browser account-switch coverage |
+| PRES-J03/J08 | Add opens review without POST; existing job/company/notification navigation | Presentation only | Existing no-write command test, exact destination browser test, job/operation route tests |
+| PRES-S02 | Owner-local notifications, read/dismiss/operation link | Explicit unread label and stale-load protection | `notifications-popover.test.tsx` read/dismiss/link/empty/error/stale cases |
+| PRES-W11/W12 | Existing operation links and task state | Bell still routes to `/operations`; no task completion side effect | Existing notification/operation tests; synthetic browser read/dismiss probe |
+
+The route/provider tree, API authentication, notification store, command actions, shell header triggers and domain workflows are unchanged. Existing rendering is retained and consolidated; there is no new command platform, Documents/CV search, task producer, email delivery or global AI assistant.
+
+## Verification and visual evidence
+
+The inherited P5-01 baseline is backend **918**, frontend **365**, browser **70 actual passes + unchanged P2-D01 expected failure**, rate-limit **9**, ingress **6**, PDF **1**, configuration **3**. Final P5-02 counts and commands are recorded below after the final code change.
+
+| Check | Final result |
+|---|---|
+| Backend Release tests | **918/918 passed**, zero skipped; unchanged from P5-01 |
+| Frontend Jest | **373/373 passed across 77 suites**; +8 focused cases (search failure/retry, close/account and query races, input/result keyboard operation, stale notification load/read navigation, notification failure/retry) |
+| Complete Chromium browser | **74 actual passes + unchanged P2-D01 expected failure**, zero unexpected/flaky cases; +4 four-mode utility journeys from P5-01. `PLAYWRIGHT_STATIC_EXPORT=true PLAYWRIGHT_PREBUILT_EXPORT=true npm.cmd run test:e2e -- --reporter=list,json`; accepted result `.artifacts/p5-02-browser-accepted.json` |
+| TypeScript / edited E2E TypeScript / lint | Passed (`npm.cmd run typecheck`; E2E `tsc --project ../.artifacts/p5-00-e2e-tsconfig.json --noEmit`; `npm.cmd run lint`) |
+| Frontend production build / API Release build | Passed; API Release build `-warnaserror` has zero warnings/errors |
+| Rate-limit / ingress / PDF / configuration | **9 / 6 / 1 / 3 passed** using their existing local Playwright configurations and `python scripts/test-ingress.py` |
+| Secret / whitespace / documentation links | Tracked-secret scan and working/staged `git diff --check` passed; current/root Markdown links **134 documents, zero missing local targets** (historical archive excluded) |
+
+Supply-chain, model-evaluation harness and browser-extension local checks passed **3 / 5 / 3**. These do not certify live external providers. Accepted backend TRX and frontend JSON reports are in ignored `.artifacts/redesign-p5-02/` and `.artifacts/p5-02-jest-accepted.json`.
+
+The final production-browser run and a focused repeat passed four utility journeys: light/English and dark/English at 1440px; light/Bokmål and dark/Bokmål at 390px. They exercised search outage, keyboard command activation, unread/read/dismiss and captured both utility overlays. Scoped axe scans of the command error and notification panel had zero violations; their incomplete nodes are not counted as passes. Eight final-build captures are under `visual/`. Direct review confirmed the light desktop error alert remains readable and the dark Bokmål phone notification panel fits below the app bar without covering its own actions. Manual screen-reader operation, zoom/forced-colour behavior and provider outage timing remain explicit validation gaps.
+
+**Acceptance status: conditional.** The [approved plan](../PHASE5_PLAN.md#p5-02--global-shell-utilities) requires a manual screen-reader command and notification task, or explicit blocking of accessibility acceptance pending operator proof. Automated axe and keyboard tests do not substitute for that task. A Windows operator should use Narrator/Edge or NVDA/Chrome on the committed build: open search with Ctrl+K, hear the dialog/search name and settled count, move between grouped actions with arrow/Home/End and Tab, activate a job/company result, close with Escape and confirm focus return; open the bell, hear loading/error/unread state, then read, dismiss and open an operation link. Repeat representative English/Bokmål and light/dark states. Record the spoken names/order, any silent state transition, and screenshot or short recording with credentials hidden. Until this passes, P5-02 is committed but **P5-03 progression is blocked** under the sequential gate.
+
+## Remaining boundaries
+
+- P5-00-D02 Jobs browser Back focus and P4-05-O01 localized table display still gate P5-03 acceptance.
+- P4-04-O02 SQLite concurrent-write contention remains a separate backend reliability defect. P5-02 adds no polling or writes; browser probes use local synthetic accounts and no external provider.
+- F04 requires production ingress evidence. P2-D01 requires native package proof. Neither is closed by this UI checkpoint.
+- P5-05 quick preview stays deferred; P5-04b Table/Board parity, P5-08b native package proof and P5-09–14 CV revision/rendering proof retain their separate gates.
+
+Rollback is limited to the two utility components, their localized labels, and tests; all existing routes and data remain valid.
@@ -5,6 +5,7 @@ Status reconciled: 2026-09-21.
 ## Current repository work

 - **P5-01 — AppShell/grouped navigation complete:** existing destinations are grouped under Dashboard, Job search, Career, Admin and Account; expanded/rail/mobile access, parent/child current semantics, skip/main and route-heading focus have automated and visual evidence. Final baseline: 918 backend, 365 frontend, 70 browser passes plus unchanged P2-D01 expected failure. [Record](../redesign/phase-5/p5-01/README.md). P5-02 remains separate; no route/provider/business change or B07 work.
+- **P5-02 — global shell utilities implemented, accessibility acceptance conditional:** command error/retry and stale-result isolation, grouped existing commands, keyboard selection, and notification stale-load/read/dismiss presentation pass 918 backend, 373 frontend and 74 actual browser tests plus unchanged P2-D01 expected failure. [Record](../redesign/phase-5/p5-02/README.md). P5-02-D01 requires a manual screen-reader utility task before P5-03 progression; F04 remains open.
 - **P5-00 — complete, P5-01 GO:** [record](../redesign/phase-5/p5-00/README.md) covers the five bounded shell gates, shared 1024px navigation boundary and open-drawer resize lifecycle. P5-00-D01 is closed with the existing fixed clock injected into the test; backend rerun is 916/916. No grouped-navigation redesign or B07 work in that checkpoint. F04 remains open.
 - **P5-00-D02 — open Jobs browser-Back focus debt:** after the workspace actually renders, browser Back preserves the query but does not restore row focus. The explicit workspace Back button carries the existing focus contract. Corrected browser evidence distinguishes them; no application behavior changed. Resolve before affected P5-03/08 navigation migration. [Evidence](../redesign/phase-5/p5-00/README.md#inherited-density-navigation-oracle-corrected).
 - **Phase 5 plan:** [bounded plan](../redesign/phase-5/README.md) maps all 57 contracts/31 routes. Board integration, native package and CV revision/rendering gates apply only to dependent slices. F04 remains open.