ledgrab/plans/activity-log/phase-6-dashboard-settings.md

Phase 6: Dashboard widget + Settings retention panel + docs

Status: ✅ Done Parent plan: 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

• 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.
• 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.
• 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.
• 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

• All tasks completed
• Code follows frontend conventions (i18n ×3, icons, selectors, CSS vars, settings pattern)
• No unintended side effects
• 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.