From 3d0a4d289bf252fc4928b87172cffedceaf54c2d Mon Sep 17 00:00:00 2001 From: hsiegeln <37154749+hsiegeln@users.noreply.github.com> Date: Tue, 21 Apr 2026 09:43:19 +0200 Subject: [PATCH] =?UTF-8?q?docs(alerts):=20Design=20spec=20=E2=80=94=20des?= =?UTF-8?q?ign-system=20alignment=20for=20/alerts=20pages?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rework all pages under /alerts to use @cameleer/design-system components and tokens. Unified DataTable shell for Inbox/All/History with expandable rows; DataTable + Dropdown + ConfirmDialog for Rules list; FormField grid + DataTable for Silences; DS Alert for wizard banners. Replaces undefined CSS variables (--bg, --fg, --muted, --accent) with DS tokens and removes raw /
` (RulesList, Silences), raw `
` → `DataTable` inside `tableStyles.tableSection`. +- Columns: **Name (Link) | Kind (Badge) | Severity (SeverityBadge) | Enabled (Toggle) | Targets (count) | Actions**. +- Actions cell: DS `Dropdown` for **Promote to env** (replaces raw `
` → `DataTable` below the form. +- Columns: **Matcher (MonoText) | Reason | Starts | Ends | End action**. +- `End` action → `ConfirmDialog`. +- Empty state: `EmptyState` "No active or scheduled silences." + +### Rule editor wizard (`/alerts/rules/new`, `/alerts/rules/:id`) + +Keep the current custom tab stepper — DS has no `Stepper`, and the existing layout is appropriate. + +Changes: +- `wizard.module.css` — replace undefined tokens with DS tokens. `.wizard` uses `--space-md` gap; `.steps` underline uses `--border-subtle`; `.stepActive` border uses `--amber` (the DS accent color); `.step` idle color uses `--text-muted`, active/done uses `--text-primary`. +- Promote banner → DS ``. +- Warnings block → DS `` with the list as children. +- Step body wraps in `sectionStyles.section` for card affordance matching other forms. + +## Shared changes + +### `alerts-page.module.css` + +Reduced to layout-only: + +```css +.page { + padding: var(--space-md); + display: flex; + flex-direction: column; + gap: var(--space-md); +} +.toolbar { + display: flex; + justify-content: space-between; + align-items: center; + gap: var(--space-sm); +} +.filterBar { + display: flex; + gap: var(--space-sm); + align-items: center; +} +``` + +Delete: `.row`, `.rowUnread`, `.body`, `.meta`, `.time`, `.message`, `.actions`, `.empty` — all replaced by DS components. + +### `AlertRow.tsx` + +**Delete.** Logic migrates into: +- A column renderer for the Title cell (handles the `Link` + `markRead` side-effect on click). +- An `expandedContent` renderer shared across the three list pages (extracted into `ui/src/pages/Alerts/alert-expanded.tsx`). +- An Ack action button rendered via DataTable `Actions` column. + +### `ConfirmDialog` migration + +Replaces native `confirm()` in `RulesListPage` (delete), `SilencesPage` (end), and the wizard if it grows a delete path (not currently present). + +### Helpers + +Two small pure-logic helpers, co-located in `ui/src/pages/Alerts/`: + +- `time-utils.ts` — `formatRelativeTime(iso: string, now?: Date): string` returning `2m ago` / `1h ago` / `3d ago`. With a Vitest. +- `severity-utils.ts` — `severityToAccent(severity: AlertSeverity): DataTableRowAccent` mapping `CRITICAL→error`, `MAJOR→warning`, `MINOR→warning`, `INFO→info`. With a Vitest. + +## Components touched + +| File | Change | +|------|--------| +| `ui/src/pages/Alerts/InboxPage.tsx` | Rewrite: DataTable + bulk toolbar + EmptyState | +| `ui/src/pages/Alerts/AllAlertsPage.tsx` | Rewrite: DataTable + ButtonGroup filter + EmptyState | +| `ui/src/pages/Alerts/HistoryPage.tsx` | Rewrite: DataTable + DateRangePicker + EmptyState | +| `ui/src/pages/Alerts/RulesListPage.tsx` | Table → DataTable; select → Dropdown; confirm → ConfirmDialog | +| `ui/src/pages/Alerts/SilencesPage.tsx` | Table → DataTable; FormField grid; confirm → ConfirmDialog | +| `ui/src/pages/Alerts/AlertRow.tsx` | **Delete** | +| `ui/src/pages/Alerts/alert-expanded.tsx` | **New** — shared expandedContent renderer | +| `ui/src/pages/Alerts/time-utils.ts` | **New** | +| `ui/src/pages/Alerts/time-utils.test.ts` | **New** | +| `ui/src/pages/Alerts/severity-utils.ts` | **New** | +| `ui/src/pages/Alerts/severity-utils.test.ts` | **New** | +| `ui/src/pages/Alerts/alerts-page.module.css` | Slim down to layout-only, DS tokens | +| `ui/src/pages/Alerts/RuleEditor/wizard.module.css` | Replace legacy tokens → DS tokens | +| `ui/src/pages/Alerts/RuleEditor/RuleEditorWizard.tsx` | Promote banner / warnings → DS `Alert`; step body → section-card wrap | + +## Testing + +1. **Unit (Vitest):** + - `time-utils.test.ts` — relative time formatting at 0s / 30s / 5m / 2h / 3d / 10d boundaries. + - `severity-utils.test.ts` — all four severities map correctly. +2. **Component tests:** + - Existing `AlertStateChip.test.tsx`, `SeverityBadge.test.tsx` keep passing (no change). + - `NotificationBell.test.tsx` — unchanged (this component already uses DS correctly per audit). +3. **E2E (Playwright):** + - Inbox empty state renders. + - AllAlerts filter ButtonGroup switches active state and requery fires. + - Rules list delete opens ConfirmDialog, confirms, row disappears. + - Wizard promote banner renders as `Alert`. +4. **Manual smoke:** + - Light + dark theme on all five pages — verify no raw `
` borders bleeding through; all surfaces use DS card shadows. + - Screenshot comparison pre/post via already-present Playwright config. + +## Open questions + +None — DS v0.1.56 ships every primitive we need (`DataTable`, `EmptyState`, `Alert`, `ButtonGroup`, `Dropdown`, `ConfirmDialog`, `DateRangePicker`, `FormField`, `MonoText`). If a gap surfaces during implementation, flag it as a separate DS-change discussion per user's standing rule. + +## Out of scope + +- Keyboard shortcuts (j/k nav, e to ack) — future enhancement. +- Grouping alerts by rule (collapse duplicates) — future enhancement. +- `MustacheEditor` visual restyling — separate concern. +- Replacing native `confirm()` outside `/alerts` — project-wide pattern; changing it all requires separate decision. + +## Migration risk + +- **Low.** Changes are localized to `ui/src/pages/Alerts/` plus one CSS module file for the wizard. No backend, no DS, no router changes. +- Openapi schema regeneration **not required** (no controller changes). +- Existing tests don't exercise feed-row DOM directly (component tests cover badges/chips only), so row-to-table conversion won't break assertions.