# Phase 6: Dashboard widget + Settings retention panel + docs

**Status:** ✅ Done
**Parent plan:** [PLAN.md](./PLAN.md)
**Domain:** frontend  ·  uses the `frontend-design` skill

## Objective

Add the two secondary surfaces: a compact **Recent Activity** widget on the Dashboard linking
to the full tab, and a **Settings** panel for retention configuration (+ clear + export entry)
positioned beside the existing Log Viewer with a clear "what's the difference" note. Update
docs/tutorials.

## Tasks

- [x] Dashboard **Recent Activity** widget (`features/dashboard.ts` + dashboard CSS):
  - Compact card showing the latest ~5 entries (severity icon, relative time, message).
  - Reuse the Phase 5 render helper (don't duplicate row markup).
  - Live update via `server:activity_logged` (prepend, cap to N).
  - **View all →** navigates to the Activity tab (`switchTab('activity_log')`).
  - Respect the existing dashboard card layout/toggle system; localized; empty state.
- [x] **Settings** retention panel (`features/settings.ts` + `templates/modals/settings.html`):
  - New rail entry `Activity Log` (beside the existing **Log Viewer**).
  - Controls: `enabled` toggle, `max_days` number, `max_entries` number → `GET/PUT
    /activity-log/settings`. Save → toast; validation feedback.
  - **Clear log** button (confirm dialog) → `DELETE /activity-log`; **Export** button →
    `/activity-log/export`.
  - One-line note distinguishing this persistent audit log from the ephemeral debug Log Viewer
    (cross-link both ways).
  - i18n for all controls/labels/hints.
- [x] Docs: update user-facing docs/README/feature list for the new Activity tab + retention
  settings + export (and the audit-vs-debug-log distinction). Keep it brief.
- [x] Tutorials/cross-links: ensure the Settings tutorial (if any) and tab tour mention the
  panel; `tour.*`/`settings.*` i18n keys in all 3 locales.

## Files to Modify/Create

- `server/src/ledgrab/static/js/features/dashboard.ts` — modify: Recent Activity widget
- `server/src/ledgrab/static/css/dashboard.css` (or relevant sheet) — modify: widget styles
- `server/src/ledgrab/static/js/features/settings.ts` — modify: retention panel + handlers
- `server/src/ledgrab/templates/modals/settings.html` — modify: rail entry + panel HTML
- `server/src/ledgrab/static/js/app.ts` / `global.d.ts` — modify: new window handlers
- `server/src/ledgrab/static/locales/{en,ru,zh}.json` — modify: i18n keys
- docs (README / feature list / relevant context doc) — modify: brief feature documentation

## Acceptance Criteria

- Dashboard shows a live Recent Activity widget; **View all →** opens the Activity tab.
- Settings panel reads/writes retention settings, clears (with confirm + auth), and exports.
- Audit-log vs debug-Log-Viewer distinction is explicit and cross-linked.
- Fully localized (en/ru/zh); empty/loading states; consistent with app design.
- `npx tsc --noEmit` clean; `npm run build` succeeds. No plain `<select>`; SVG icons only.

## Notes

- **Use the `frontend-design` skill** for the widget + settings panel layout.
- Reuse Phase 5's render helper and i18n namespace — no duplicated row markup or keys.
- Settings UI model: `features/settings.ts switchSettingsTab` + `modals/settings.html` rail.
- Frontend-only phase → run `tsc --noEmit` + `npm run build`; do NOT run pytest/ruff (docs +
  TS only).
- Backup/restore cross-ref: no `STORE_MAP` edit needed (whole-DB backup covers the table) —
  confirm nothing else (graph editor) needs syncing for this viewer (verified: not needed).

## Review Checklist

- [x] All tasks completed
- [x] Code follows frontend conventions (i18n ×3, icons, selectors, CSS vars, settings pattern)
- [x] No unintended side effects
- [x] Build passes (`tsc --noEmit` + `npm run build`)
- [ ] Manual smoke: widget live-updates + links; settings save/clear/export; docs updated (recommend at final review — requires server restart)

## Handoff to Next Phase

This is the **final implementation phase**. All six phases are complete. Notes for the final reviewer:

**What was implemented in Phase 6:**

- `features/dashboard.ts`: `_loadRecentActivityWidget()`, `_renderRecentActivityList()`, `_startRecentActivityLive()` — SSE live-update listener (`server:activity_logged`) with cap-to-5 prepend logic. Widget appended after `getOrderedSections()` loop (outside the layout toggle system — always visible). Non-blocking: `.catch()` on the async load call.
- `features/settings.ts`: `loadActivityLogSettings()`, `saveActivityLogSettings()`, `activityLogSettingsExport(format)`, `clearActivityLog()` — all exported and exposed on `window` via `app.ts` + `global.d.ts`.
- `templates/modals/settings.html`: Activity Log rail entry (System group, cyan channel) + full panel (`id="settings-panel-activity_log"`) with enabled toggle, `max_days`/`max_entries` inputs, Save, CSV/JSON export, Clear (danger zone). Audit-vs-debug distinction note with cross-links in both directions (`closeSettingsModal(); openLogOverlay()` and `closeSettingsModal(); switchTab('activity_log')`).
- `static/css/activity-log.css`: `.dal-*` dashboard widget styles + `.ds-info-note` / `.ds-inline-link` settings panel utilities appended (no new CSS file).
- `static/locales/{en,ru,zh}.json`: 32 new keys each under `dashboard.section.recent_activity`, `dashboard.recent_activity.*`, `settings.tab.activity_log`, `settings.activity_log.*`.
- `README.md`: "### Activity Log" section documenting tab, retention settings, export, and audit-vs-debug distinction.

**Reused Phase 5 helpers (no duplication):**

- `fetchRecentEntries(limit)` and `renderCompactEntry(entry)` — new public exports added to `activity-log.ts` in Phase 6 (not duplicated in dashboard.ts).
- All `.al-*` CSS classes from Phase 5 are reused in the compact rows inside the widget.

**Build verification:** `tsc --noEmit` clean, `npm run build` passed (2.8 MB bundle, 258 ms) at time of implementation.

**Remaining manual smoke test (requires server restart):**

- Dashboard widget loads recent entries, prepends live on new activity, "View all →" switches to Activity tab.
- Settings panel reads/writes retention, Save shows toast, Clear prompts confirm then deletes, Export downloads authed blob.
- Cross-links: note in Settings opens Log Viewer overlay; note in Log Viewer links back to Activity tab.

**Outstanding open note from PLAN.md:** The manual browser smoke test across the whole feature (P5 note) remains open — it requires a server restart to exercise the live API endpoints. Recommend as first step in the final review session.