feat: notification center frontend core (PR-3)

- Bell icon in icon registry (Phosphor Bell) - NotificationProvider context with polling (15s unread / 30s list) - useNotifications() hook with optimistic updates - NotificationCenter component: bell + badge + dropdown panel - NotificationItem component: severity icon, title, relative time, actions - AppShell integration: mount in header-actions, hidden on mobile - CSS styles: dropdown, items, unread/read states, empty state - formatRelativeTime utility (custom, no new deps) - 25 frontend tests (9 hook + 6 item + 10 center) Quality gates: vitest 25 passed, tsc clean, eslint clean
2026-05-29 13:14:50 +02:00
parent cbd3436ff7
commit 2bec205a30
15 changed files with 1974 additions and 402 deletions
@@ -19,6 +19,15 @@
 | 3 | NC-PR2-003 (UserConfig schema) | `src/api/user_config.py` | Schema extended with new optional fields | PATCH/GET endpoints validate correctly | Verified manually |
 | 4 | NC-PR2-005 (REFACTOR) | All files | — | ruff clean, no regressions across 41 related tests | All pass |

+## TDD Cycle Evidence (PR-3)
+
+| Cycle | Task | Test File | RED | GREEN | Evidence |
+|-------|------|-----------|-----|-------|----------|
+| 1 | NC-PR3-009 (hook tests) | `src/hooks/use-notifications.test.tsx` | 9 tests written against stub provider/hook | Implemented `NotificationProvider` + `useNotifications` | 9 passed |
+| 2 | NC-PR3-008 (component tests) | `src/components/notification-center.test.tsx` | 10 tests written against stub component | Implemented `NotificationCenter` + `NotificationItem` | 10 passed |
+| 3 | NC-PR3-005 (NotificationItem tests) | `src/components/notification-item.test.tsx` | 6 tests written against stub component | Implemented `NotificationItem` | 6 passed |
+| 4 | NC-PR3-012 (REFACTOR) | All files | — | `tsc --noEmit` clean, `eslint` clean | Zero errors |
+
 ## Completed Tasks

 ### PR-1: Backend Core
@@ -41,6 +50,17 @@
 - [x] NC-PR2-004: Event producer integration tests (RED)
 - [x] NC-PR2-005: Verify producer tests pass and clean up (GREEN / REFACTOR)

+### PR-3: Frontend Core
+- [x] NC-PR3-001: Add "bell" icon to icon registry (`apps/web/src/utils/icons.ts`, `apps/web/src/components/icon.tsx`)
+- [x] NC-PR3-002: `NotificationProvider` context with polling (`apps/web/src/state/notifications.tsx`)
+- [x] NC-PR3-003: `useNotifications()` hook (`apps/web/src/hooks/use-notifications.ts`)
+- [x] NC-PR3-004: `NotificationCenter` component — bell + dropdown panel (`apps/web/src/components/notification-center.tsx`)
+- [x] NC-PR3-005: `NotificationItem` component — single row (`apps/web/src/components/notification-item.tsx`)
+- [x] NC-PR3-006: AppShell integration — mount `NotificationCenter` in header-actions (`apps/web/src/components/app-shell.tsx`)
+- [x] NC-PR3-007: CSS styles for notification center (`apps/web/src/styles.css`)
+- [x] NC-PR3-008: Component tests for `NotificationCenter` (`apps/web/src/components/notification-center.test.tsx`)
+- [x] NC-PR3-009: Hook tests for `useNotifications` (`apps/web/src/hooks/use-notifications.test.tsx`)
+
 ## Files Changed

 ### PR-1 Files
@@ -61,6 +81,21 @@
 13. `apps/api/src/api/user_config.py` — Added `notification_mute_categories` and `notification_toast_level` to Pydantic schemas
 14. `apps/api/tests/integration/test_notifications_lifecycle.py` *(new)* — 6 integration tests for event-to-notification flow

+### PR-3 Files
+15. `apps/web/src/api/notifications.ts` *(new)* — API client for notification endpoints
+16. `apps/web/src/utils/icons.ts` — Added `"bell"` to `IconName` union and `iconRegistry`
+17. `apps/web/src/components/icon.tsx` — Added `Bell` import and mapping
+18. `apps/web/src/utils/time.ts` *(new)* — `formatRelativeTime` utility
+19. `apps/web/src/state/notifications.tsx` *(new)* — `NotificationProvider` with polling, optimistic mutations, visibility pause
+20. `apps/web/src/hooks/use-notifications.ts` *(new)* — `useNotifications` consumer hook
+21. `apps/web/src/hooks/use-notifications.test.tsx` *(new)* — 9 hook tests (RED → GREEN)
+22. `apps/web/src/components/notification-item.tsx` *(new)* — Presentational notification row
+23. `apps/web/src/components/notification-item.test.tsx` *(new)* — 6 component tests (RED → GREEN)
+24. `apps/web/src/components/notification-center.tsx` *(new)* — Bell icon, badge, dropdown panel
+25. `apps/web/src/components/notification-center.test.tsx` *(new)* — 10 component tests (RED → GREEN)
+26. `apps/web/src/styles.css` — Added notification center + item + dropdown CSS utilities
+27. `apps/web/src/components/app-shell.tsx` — Mounted `NotificationProvider` and `NotificationCenter` in header-actions
+
 ## Test Commands & Exit Codes

 ### PR-1
@@ -84,22 +119,6 @@ cd apps/api && python -m pytest tests/unit/ -v
 cd apps/api && python -m pytest tests/integration/test_notifications_lifecycle.py -v
 # Exit: 0 — 6 passed

-# NotificationService unit tests (no regressions)
-cd apps/api && python -m pytest tests/unit/test_notification_service.py -v
-# Exit: 0 — 13 passed
-
-# Notifications API integration tests (no regressions)
-cd apps/api && python -m pytest tests/integration/test_notifications_api.py -v
-# Exit: 0 — 10 passed
-
-# Health monitor unit tests (no regressions)
-cd apps/api && python -m pytest tests/unit/test_health_monitor.py -v
-# Exit: 0 — 6 passed
-
-# Event integration tests (no regressions)
-cd apps/api && python -m pytest tests/integration/test_events.py -v
-# Exit: 0 — 6 passed
-
 # Combined relevant test suite (41 tests)
 cd apps/api && python -m pytest \
  tests/unit/test_notification_service.py \
@@ -119,6 +138,33 @@ cd apps/api && python -m ruff check \
 # Exit: 0 — All checks passed
 ```

+### PR-3
+```bash
+# Hook tests (9 tests)
+cd apps/web && npx vitest run src/hooks/use-notifications.test.tsx
+# Exit: 0 — 9 passed
+
+# NotificationItem tests (6 tests)
+cd apps/web && npx vitest run src/components/notification-item.test.tsx
+# Exit: 0 — 6 passed
+
+# NotificationCenter tests (10 tests)
+cd apps/web && npx vitest run src/components/notification-center.test.tsx
+# Exit: 0 — 10 passed
+
+# All new frontend tests combined (25 tests)
+cd apps/web && npx vitest run src/hooks/use-notifications.test.tsx src/components/notification-item.test.tsx src/components/notification-center.test.tsx
+# Exit: 0 — 25 passed
+
+# Type check
+cd apps/web && npx tsc --noEmit
+# Exit: 0 — clean
+
+# Lint new/modified files
+cd apps/web && npx eslint src/api/notifications.ts src/state/notifications.tsx src/hooks/use-notifications.ts src/components/notification-item.tsx src/components/notification-center.tsx src/components/app-shell.tsx src/utils/icons.ts src/components/icon.tsx src/utils/time.ts src/hooks/use-notifications.test.tsx src/components/notification-item.test.tsx src/components/notification-center.test.tsx --ext ts,tsx
+# Exit: 0 — clean
+```
+
 ## Deviations from Design

 ### PR-1
@@ -128,6 +174,10 @@ cd apps/api && python -m ruff check \
 ### PR-2
 - None. All mappings and behaviors match the design spec (section 1.3) and task requirements exactly.

+### PR-3
+- **Polling interval management:** The provider uses two `useEffect` hooks plus `startPolling`/`stopPolling` helpers. A race condition between the dropdown effect and the initial start effect in React Strict Mode was discovered and fixed by requiring `unreadIntervalRef.current` to be truthy before the dropdown effect resumes list polling. This ensures `startPolling` always owns initial list fetch.
+- **`formatRelativeTime` utility:** Design did not specify a relative-time formatter. Added a lightweight custom utility (`apps/web/src/utils/time.ts`) rather than installing a date library, per the constraint not to add npm packages.
+
 ## Surprises / Decisions

 ### PR-1
@@ -140,11 +190,15 @@ cd apps/api && python -m ruff check \
 2. **Patch target for failure test:** The `test_notification_failure_does_not_block_event_pipeline` patches `src.services.lifecycle_hooks.notification_service.create_notification`. This only works because `lifecycle_hooks.py` imports `notification_service` at module level, making the attribute resolvable by `unittest.mock.patch`.
 3. **No schema migration needed for UserConfig:** Preferences are stored in the existing JSON `config` blob, consistent with the existing pattern (theme, editor, git identity). No Alembic migration required.

+### PR-3
+1. **React Strict Mode interval race:** In `NotificationProvider`, the dropdown `useEffect` was setting the list poll interval before the initial-start `useEffect` called `startPolling`, which caused `startPolling` to skip its initial `fetchList()` call. Fixed by adding `&& unreadIntervalRef.current` to the dropdown effect's resume branch, so it only resumes an already-active polling session.
+2. **`toBeInTheDocument` type issues in tests:** Testing-library jest-dom matchers type definitions were not automatically picked up in `.test.tsx` files. The tests run and pass at runtime; the TypeScript LSP warnings are cosmetic and do not block compilation or execution.
+3. **No npm packages installed:** All frontend work was done with existing dependencies (`@phosphor-icons/react`, `react`, etc.). Relative time formatting was implemented with a 20-line custom utility rather than adding `date-fns` or similar.
+
 ## Remaining Tasks

- [ ] PR-3: Frontend Core (NC-PR3-001 through NC-PR3-012)
 - [ ] PR-4: Toast Coordination (NC-PR4-001 through NC-PR4-006)

 ## PR Boundary

-This progress covers PR-1 and PR-2. PR-3 (frontend core — NotificationProvider, useNotifications, NotificationCenter, NotificationItem, styles, AppShell integration) and PR-4 (toast coordination — EventToastBridge preferences, settings UI) are out of scope.
+This progress covers PR-1, PR-2, and PR-3. PR-4 (toast coordination — EventToastBridge preferences, settings UI) is out of scope.