Keith Solomon
71 lines
3.1 KiB
Markdown
71 lines
3.1 KiB
Markdown
# Newsletter UI Implementation Plan
|
|
|
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
|
|
**Goal:** Replace the rough web views with a functional two-pane newsletter browser that defaults to the latest issue and can switch to all issues.
|
|
|
|
**Architecture:** Keep the current Express/server-rendered UI. Add focused SQLite read methods to `CatalogDatabase`, render reusable layout/navigation/table helpers in `src/web/views.ts`, and wire new routes in `src/web/app.ts` for dashboard, newsletter browser, all links, sponsors, dead links, and runs. Use query parameters for selected newsletter, issue scope, link search, and category filters.
|
|
|
|
**Tech Stack:** TypeScript, Express, Node `node:sqlite`, server-rendered HTML/CSS, Vitest.
|
|
|
|
---
|
|
|
|
### Task 1: Database Read Models
|
|
|
|
**Files:**
|
|
|
|
- Modify: `src/database/store.ts`
|
|
- Test: `tests/web.test.ts`
|
|
|
|
- [ ] Write failing tests that a fixture database can return newsletter summaries with issue/link/sponsor counts.
|
|
- [ ] Write failing tests that selected newsletter links default to the latest issue and can include all issues.
|
|
- [ ] Add `newsletterSummaries()`, `newsletterById()`, `newsletterLinks()`, `categoriesForNewsletter()`, and `allLinks()` read methods.
|
|
- [ ] Run `npm test -- tests/web.test.ts`.
|
|
|
|
### Task 2: Two-Pane Newsletter Page
|
|
|
|
**Files:**
|
|
|
|
- Modify: `src/web/views.ts`
|
|
- Modify: `src/web/app.ts`
|
|
- Test: `tests/web.test.ts`
|
|
|
|
- [ ] Write failing tests that `/newsletters` renders a two-pane layout, newsletter search input, selected state, latest/all issue controls, category filter, and external link attributes.
|
|
- [ ] Implement reusable page layout with dark default styling, light mode toggle, global nav, responsive two-pane layout, and empty states.
|
|
- [ ] Implement `/newsletters` with query params: `newsletter`, `scope`, `q`, `category`.
|
|
- [ ] Run `npm test -- tests/web.test.ts`.
|
|
|
|
### Task 3: Global Views and Smoke
|
|
|
|
**Files:**
|
|
|
|
- Modify: `src/web/app.ts`
|
|
- Modify: `src/web/views.ts`
|
|
- Modify: `scripts/smoke.mjs`
|
|
- Test: `tests/web.test.ts`
|
|
|
|
- [ ] Write failing tests that dashboard, all links, sponsored links, dead links, and runs use the new layout.
|
|
- [ ] Update `/`, `/links`, `/sponsors`, `/dead-links`, and `/runs` to use the shared layout and table helpers.
|
|
- [ ] Keep `nlc serve --help` in smoke validation.
|
|
- [ ] Run `npm test -- tests/web.test.ts`.
|
|
|
|
### Task 4: Docs and Verification
|
|
|
|
**Files:**
|
|
|
|
- Add: `notes/UI Spec.md`
|
|
- Modify: `README.md`
|
|
|
|
- [ ] Track the approved UI spec.
|
|
- [ ] Document `nlc serve` and the newsletter browser behavior.
|
|
- [ ] Run `npm run lint`.
|
|
- [ ] Run `npm run format:check`.
|
|
- [ ] Run `npm run typecheck`.
|
|
- [ ] Run `npm test`.
|
|
- [ ] Run `npm run build`.
|
|
- [ ] Run `npm run smoke`.
|
|
|
|
## Self-Review
|
|
|
|
The plan covers the approved UI spec: two-pane layout, newsletter navigation, latest issue default, all-issues option, global navigation, search/filter controls, dark default, light option, mobile-friendly responsive behavior, and safe external links. It avoids a frontend build stack and keeps the first implementation functional.
|