hwilliams-dev/blog-pagination-and-categories-plan.md

# Plan: Blog Pagination, Post Categories & Category Filters

## Context / current state

- The blog is a data-only CMS: `BLOG_POSTS` in `data/content.ts` is the single source of truth (currently 2 posts). Posts are typed `BlogPost` objects with `tags: string[]` — there is no category concept today.
- Route flow: `app/blog/page.tsx` (thin server component) → `components/BlogList.tsx` (client component) → `components/BlogPostCard.tsx`. `BlogList` renders every post, newest first (`sortPostsNewestFirst`), with a staggered reveal animation (`useStaggerReveal`).
- Post detail: `app/blog/[slug]/page.tsx` renders markdown via the shared remark pipeline, with "Back To Top" / "All Posts" links.
- Styling conventions: inline styles using CSS variables (`var(--mono)`, `var(--accent)`, `var(--accent-bg)`, …) plus `styles/blog.css`. `ModList` has an established empty-state pattern ("Nothing published here yet."). Tag chips in `BlogPostCard` define the visual language for small mono chips.
- Stack: Next.js 16 (App Router) + React 19. No `useSearchParams` / `Suspense` usage anywhere yet.

## Goals

1. Paginate the blog directory (`/blog` list view).
2. Give each blog post a single `category` (free-form `tags` stay as-is).
3. Filter the blog directory by category: chip row + URL param, with a stable URL shape.

## URL design

| URL | Meaning |
|---|---|
| `/blog` | All posts, page 1 |
| `/blog?page=2` | Page 2 of all posts |
| `/blog?category=meta` | All `meta` posts, page 1 |
| `/blog?category=meta&page=2` | Page 2 of `meta` posts |

- Category values are stored as slugs (kebab-case, lowercase) in the data, e.g. `meta`, `development`. A `categoryLabel(slug)` helper derives the display string ("meta", "Development").
- All URL building goes through one helper (`blogHref({ page?, category? })`) so the shape has a single source of truth.

## Changes by file

### 1. `data/content.ts`
- Extend the `BlogPost` type: add `category: string; // slug, e.g. "meta" — one category per post` (keep `tags` untouched).
- Update existing posts: "Adding a blog tab to a portfolio site" → `category: "development"`; "Hello, world. This is the new blog." → `category: "meta"`.
- New exports:
  - `POSTS_PER_PAGE = 3` — small enough that pagination is visible as soon as a few posts exist.
  - `blogCategories(): string[]` — deduplicated, alphabetically sorted categories in use (derived from `BLOG_POSTS`, no new config).
  - `categoryLabel(slug: string): string` — slug → display string.
  - `postsForCategory(slug?: string): BlogPost[]` — all posts when omitted, otherwise posts whose `category` matches.
  - `paginate<T>(items: T[], page: number, perPage: number): { items: T[]; page: number; totalPages: number; total: number; startIndex: number; endIndex: number }` — pure helper that also **clamps** `page` into `[1, totalPages]` (so `?page=99` lands on the last page instead of erroring).

### 2. `components/BlogList.tsx` (main change)
- Keep it a client component, but split it: default export `BlogList` wraps an inner `BlogListInner` (which calls `useSearchParams()`) in `<Suspense fallback={…}>`. **This is required** — `useSearchParams` on a statically rendered page makes `next build` fail without a Suspense boundary.
- Read params: `page = Number(searchParams.get("page") ?? 1)`, `category = searchParams.get("category") ?? undefined`.
- Data pipeline: `postsForCategory(category)` → `sortPostsNewestFirst` → `paginate(…, POSTS_PER_PAGE)`.
- **Category filter row** (chips, above the post stack):
  - `all` + one chip per entry from `blogCategories()`, styled like the tag chips in `BlogPostCard` (mono 11px, padded, 4px radius); active chip uses `var(--accent)` / `var(--accent-bg)`.
  - Each chip is a `next/link` to `blogHref({ category })` — switching categories **drops `page`** from the URL.
- **Pagination controls** (below the stack):
  - `‹ Prev` / `Next ›` plus numbered page buttons (fine at this scale; revisit if we ever exceed ~9 pages).
  - Reuse the existing `expand-on-hover-button` class so links match the site's look; render disabled states as non-links on first/last page (no dead hrefs).
  - Mono/muted count line: `showing 1–3 of 5`.
- **Empty state**: when the filtered list is empty (e.g. unknown category slug) render "No posts in this category yet." in the `ModList` empty-state style. A query param shouldn't 404 — degrade gracefully.
- **Stagger animation**: `useStaggerReveal`'s effect only re-runs when its `count` changes, so re-trigger it per page by keying the card container with `${category ?? "all"}-${page}`.
- `BlogPostCard` stays unchanged (out of scope).

### 3. `app/blog/page.tsx`
- No change: still renders `<BlogList />`; filtering/pagination are self-managed via search params.

### 4. (Optional stretch) `app/blog/category/[category]/page.tsx`
- Thin server component: `notFound()` if the slug is not in `blogCategories()`, otherwise render `<BlogList category={slug} />`.
- This requires `BlogList` to accept an optional `category` prop that takes precedence over the search param (the param still controls `page`). Chip links on that page use the `/blog?category=…` form so navigation stays consistent.
- Marked optional: the chips + `?category=` param already deliver the category feature; this route is only for cleaner shareable URLs/SEO. If time is short, skip it.

### 5. `styles/blog.css`
- Add, matching the file's existing conventions:
  - `.blog-category-filters` — flex row, wrap, gap, margin below the heading.
  - `.blog-category-chip` (+ `.is-active`) — mono chip look, accent when active.
  - `.blog-pagination` — flex row, `space-between`, mono ~12px, top margin.
  - `.blog-count` — muted mono count line.
  - Narrow-screen + `prefers-reduced-motion` tweaks, mirroring the existing media queries.

### 6. (Optional, low priority) `app/blog/[slug]/page.tsx`
- Show the post's category as a small chip above the content, linking to `/blog?category=<slug>`, mirroring the tag-chip look. Nice-to-have for discoverability; doesn't block the core feature.

## Out of scope

- Tag-based or multi-select filtering (tags remain display-only metadata on cards).
- Custom metadata (`generateMetadata`) per category — `/blog?category=…` reuses the existing `/blog` metadata.
- Infinite scroll — explicit pagination was chosen for keyboard access and stable URLs.
- Editing tooling for posts — the data array remains the CMS, per the site's existing architecture.

## Implementation order

1. `data/content.ts` — type, data updates, helpers. (Build should still pass; nothing consumes the new fields yet.)
2. `BlogList` — category filtering + chips (no pagination yet).
3. `BlogList` — pagination: controls, count line, clamping, stagger re-trigger key.
4. `styles/blog.css` — chip + pagination + count styles.
5. Optional: `/blog/category/[category]` route; optional post-page category chip.
6. Verification (below).

## Verification

- `npm run build` — catches the `useSearchParams`/`Suspense` issue and any type errors. Next 16 is strict about static-rendering requirements.
- `npm run lint`.
- Manual pass:
  - `/blog` shows all posts, page 1 active, `Next` disabled while `POSTS_PER_PAGE` covers everything.
  - Temporarily add a 3rd–4th fixture post → page 2 appears; `?page=2` shows the rest; `?page=99` clamps to the last page. Remove fixtures afterwards.
  - Chips: `?category=meta` shows only meta posts; Prev/Next keep the category in the URL; switching chips drops `page`.
  - Unknown category slug → empty state, no crash.
  - Post pages: "Back To Top" / "All Posts" still work; (if implemented) category chip links correctly.

## Risks / notes

- `useSearchParams` + static page ⇒ Suspense boundary is mandatory at build time (handled in step 2 of the component change).
- `useStaggerReveal` only re-runs when `count` changes ⇒ use the container key to re-trigger per page.
- Keep the design language: CSS variables, inline styles, existing button classes, no new dependencies.
- Dates are ISO and compare lexicographically — `sortPostsNewestFirst` keeps working unchanged.