From d0ab542fcdde787fb350981bbc70662f3eefc471 Mon Sep 17 00:00:00 2001
From: Chris Alfano <chris@jarv.us>
Date: Sat, 27 Jun 2026 05:30:19 -0400
Subject: [PATCH] feat(blog): excerpt fallback + tag chips (#113)

Two blog UI gaps from the spec-drift audit:

- BlogIndex (blog-index.md): when `summary` is null, fall back to the first
  paragraph of `bodyHtml` truncated to ~280 chars (plain-text, derived
  client-side from the already-sanitized HTML).
- BlogDetail (blog-detail.md): render the post's tags as chips in the footer
  linking to `/blog?tag=<handle>`. The blog response didn't carry tags, so the
  serializer now resolves them (tag-assignments where taggableType=blog_post)
  and includes a `tags` field (spec api/blog.md updated). Web type + UI added.

Tests: BlogIndex excerpt fallback; BlogDetail chips present/absent; API blog
suite still green (tags in response).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 apps/api/src/services/blog-post.ts            | 13 +++-
 .../api/src/services/serializers/blog-post.ts | 14 +++-
 apps/web/src/lib/api.ts                       |  1 +
 apps/web/src/screens/BlogDetail.tsx           | 13 ++++
 apps/web/src/screens/BlogIndex.tsx            | 23 +++++-
 apps/web/tests/BlogDetail.test.tsx            | 70 +++++++++++++++++++
 apps/web/tests/BlogIndex.test.tsx             | 29 ++++++++
 specs/api/blog.md                             |  1 +
 8 files changed, 156 insertions(+), 8 deletions(-)
 create mode 100644 apps/web/tests/BlogDetail.test.tsx

diff --git a/apps/api/src/services/blog-post.ts b/apps/api/src/services/blog-post.ts
index aedceed..62f032c 100644
--- a/apps/api/src/services/blog-post.ts
+++ b/apps/api/src/services/blog-post.ts
@@ -4,7 +4,7 @@
  * Per specs/api/blog.md. Writes happen via PR to the data repo, not the
  * runtime — no mutation methods here.
  */
-import type { BlogPost } from '@cfp/shared/schemas';
+import type { BlogPost, Tag } from '@cfp/shared/schemas';
 import type { InMemoryState } from '../store/memory/state.js';
 import { serializeBlogPost, type BlogPostResponse } from './serializers/blog-post.js';
 
@@ -66,6 +66,15 @@ export class BlogPostService {
 
   #serialize(post: BlogPost): BlogPostResponse {
     const author = post.authorId ? (this.#state.people.get(post.authorId) ?? null) : null;
-    return serializeBlogPost(post, { author });
+    return serializeBlogPost(post, { author, tags: this.#tagsFor(post.id) });
+  }
+
+  #tagsFor(postId: string): Tag[] {
+    const taIds = this.#state.tagAssignmentsByTaggable.get(postId) ?? new Set<string>();
+    return [...taIds]
+      .map((taId) => this.#state.tagAssignments.get(taId))
+      .filter((ta): ta is NonNullable<typeof ta> => ta?.taggableType === 'blog_post')
+      .map((ta) => this.#state.tags.get(ta.tagId))
+      .filter((t): t is Tag => t !== undefined);
   }
 }
diff --git a/apps/api/src/services/serializers/blog-post.ts b/apps/api/src/services/serializers/blog-post.ts
index 5b5747e..e4de21d 100644
--- a/apps/api/src/services/serializers/blog-post.ts
+++ b/apps/api/src/services/serializers/blog-post.ts
@@ -1,8 +1,14 @@
 /**
  * BlogPost serializer.
  */
-import type { BlogPost, Person } from '@cfp/shared/schemas';
-import { renderMarkdown, serializePersonAvatar, type PersonAvatar } from './common.js';
+import type { BlogPost, Person, Tag } from '@cfp/shared/schemas';
+import {
+  renderMarkdown,
+  serializePersonAvatar,
+  serializeTagItem,
+  type PersonAvatar,
+  type TagItem,
+} from './common.js';
 
 export interface BlogPostResponse {
   readonly id: string;
@@ -16,13 +22,14 @@ export interface BlogPostResponse {
   readonly featuredImageUrl: string | null;
   readonly body: string;
   readonly bodyHtml: string;
+  readonly tags: TagItem[];
   readonly createdAt: string;
   readonly updatedAt: string;
 }
 
 export function serializeBlogPost(
   post: BlogPost,
-  opts: { author: Person | null },
+  opts: { author: Person | null; tags?: Tag[] },
 ): BlogPostResponse {
   return {
     id: post.id,
@@ -38,6 +45,7 @@ export function serializeBlogPost(
       : null,
     body: post.body,
     bodyHtml: renderMarkdown(post.body).html,
+    tags: (opts.tags ?? []).map(serializeTagItem),
     createdAt: post.createdAt,
     updatedAt: post.updatedAt,
   };
diff --git a/apps/web/src/lib/api.ts b/apps/web/src/lib/api.ts
index 4a9c1d7..94130a3 100644
--- a/apps/web/src/lib/api.ts
+++ b/apps/web/src/lib/api.ts
@@ -297,6 +297,7 @@ export interface BlogPostResponse {
   readonly featuredImageUrl: string | null;
   readonly body: string;
   readonly bodyHtml: string;
+  readonly tags: TagItem[];
   readonly createdAt: string;
   readonly updatedAt: string;
 }
diff --git a/apps/web/src/screens/BlogDetail.tsx b/apps/web/src/screens/BlogDetail.tsx
index e7e2a12..8fcbb1c 100644
--- a/apps/web/src/screens/BlogDetail.tsx
+++ b/apps/web/src/screens/BlogDetail.tsx
@@ -68,6 +68,19 @@ export function BlogDetail() {
       </div>
 
       <footer className="mt-10 pt-6 border-t border-border">
+        {post.tags.length > 0 && (
+          <div className="mb-4 flex flex-wrap gap-2">
+            {post.tags.map((t) => (
+              <Link
+                key={`${t.namespace}.${t.slug}`}
+                to={`/blog?tag=${encodeURIComponent(`${t.namespace}.${t.slug}`)}`}
+                className="inline-flex items-center rounded-full border border-border bg-muted px-2.5 py-0.5 text-xs text-muted-foreground hover:text-foreground"
+              >
+                {t.title}
+              </Link>
+            ))}
+          </div>
+        )}
         <Link to="/blog" className="text-primary underline">
           ← Back to all posts
         </Link>
diff --git a/apps/web/src/screens/BlogIndex.tsx b/apps/web/src/screens/BlogIndex.tsx
index 36e1253..8d3c383 100644
--- a/apps/web/src/screens/BlogIndex.tsx
+++ b/apps/web/src/screens/BlogIndex.tsx
@@ -147,15 +147,32 @@ function BlogIndexCard({ post }: { post: BlogPostResponse }) {
             ) : null}
             <time dateTime={post.postedAt}>{formatPostedAt(post.postedAt)}</time>
           </div>
-          {post.summary && (
-            <p className="text-muted-foreground mt-2 leading-relaxed">{post.summary}</p>
-          )}
+          {(() => {
+            // blog-index.md Display Rules: show `summary`; if absent, fall back
+            // to the first paragraph of bodyHtml truncated to ~280 chars.
+            const text = post.summary ?? excerptFromHtml(post.bodyHtml);
+            return text ? (
+              <p className="text-muted-foreground mt-2 leading-relaxed">{text}</p>
+            ) : null;
+          })()}
         </div>
       </article>
     </li>
   );
 }
 
+/**
+ * Plain-text excerpt from already-sanitized post HTML: the first paragraph's
+ * text, truncated to ~280 chars at a word boundary. Only strips tags for the
+ * preview — the full post renders via the server-sanitized HTML elsewhere.
+ */
+function excerptFromHtml(html: string): string {
+  const firstParagraph = /<p[^>]*>(.*?)<\/p>/is.exec(html)?.[1] ?? html;
+  const text = firstParagraph.replace(/<[^>]+>/g, '').replace(/\s+/g, ' ').trim();
+  if (text.length <= 280) return text;
+  return text.slice(0, 280).replace(/\s+\S*$/, '') + '…';
+}
+
 function formatPostedAt(iso: string): string {
   const d = new Date(iso);
   return d.toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' });
diff --git a/apps/web/tests/BlogDetail.test.tsx b/apps/web/tests/BlogDetail.test.tsx
new file mode 100644
index 0000000..a33e23e
--- /dev/null
+++ b/apps/web/tests/BlogDetail.test.tsx
@@ -0,0 +1,70 @@
+import { describe, expect, it, vi, afterEach } from 'vitest';
+import { screen, waitFor } from '@testing-library/react';
+import { Routes, Route } from 'react-router';
+import { renderScreen, mockOk } from './test-utils.js';
+import { BlogDetail } from '../src/screens/BlogDetail.js';
+import { AuthProvider } from '../src/hooks/useAuth.js';
+
+const POST = {
+  id: '01951a3c-0000-7000-8000-bbbbbbbbbbbb',
+  slug: 'roundup',
+  title: 'Civic Tech Roundup',
+  summary: null,
+  author: null,
+  postedAt: '2026-05-10T12:00:00Z',
+  editedAt: null,
+  featuredImageKey: null,
+  featuredImageUrl: null,
+  body: '# x',
+  bodyHtml: '<p>Body</p>',
+  tags: [{ namespace: 'topic', slug: 'transit', title: 'Transit' }],
+  createdAt: '2026-05-10T12:00:00Z',
+  updatedAt: '2026-05-10T12:00:00Z',
+};
+
+describe('BlogDetail tag chips', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  function mock(post: typeof POST): void {
+    vi.spyOn(globalThis, 'fetch').mockImplementation(((input: string) => {
+      if (input.startsWith('/api/auth/me')) return Promise.resolve(new Response(null, { status: 404 }));
+      if (input.startsWith('/api/blog-posts/roundup')) {
+        return Promise.resolve(
+          new Response(JSON.stringify(mockOk(post)), { status: 200, headers: { 'content-type': 'application/json' } }),
+        );
+      }
+      return Promise.resolve(new Response(null, { status: 404 }));
+    }) as typeof fetch);
+  }
+
+  function render(): void {
+    renderScreen(
+      <AuthProvider>
+        <Routes>
+          <Route path="/blog/:slug" element={<BlogDetail />} />
+        </Routes>
+      </AuthProvider>,
+      { initialEntries: ['/blog/roundup'] },
+    );
+  }
+
+  it('renders tag chips linking to /blog?tag=<handle>', async () => {
+    mock(POST);
+    render();
+    await waitFor(() => {
+      expect(screen.getByRole('link', { name: 'Transit' })).toBeInTheDocument();
+    });
+    expect(screen.getByRole('link', { name: 'Transit' })).toHaveAttribute('href', '/blog?tag=topic.transit');
+  });
+
+  it('renders no tag chips when the post has no tags', async () => {
+    mock({ ...POST, tags: [] } as unknown as typeof POST);
+    render();
+    await waitFor(() => {
+      expect(screen.getByRole('heading', { name: 'Civic Tech Roundup' })).toBeInTheDocument();
+    });
+    expect(screen.queryByRole('link', { name: 'Transit' })).not.toBeInTheDocument();
+  });
+});
diff --git a/apps/web/tests/BlogIndex.test.tsx b/apps/web/tests/BlogIndex.test.tsx
index 9b0f06b..8a4048c 100644
--- a/apps/web/tests/BlogIndex.test.tsx
+++ b/apps/web/tests/BlogIndex.test.tsx
@@ -68,6 +68,35 @@ describe('BlogIndex', () => {
     expect(screen.getByText('A short blurb.')).toBeInTheDocument();
   });
 
+  it('falls back to a bodyHtml first-paragraph excerpt when summary is null', async () => {
+    const noSummary = {
+      ...SAMPLE_POST,
+      summary: null,
+      bodyHtml: '<h1>Heading</h1><p>First paragraph of the body.</p><p>Second.</p>',
+    };
+    vi.spyOn(globalThis, 'fetch').mockImplementation(((input: string) => {
+      if (input.startsWith('/api/auth/me')) return Promise.resolve(new Response(null, { status: 404 }));
+      if (input.startsWith('/api/blog-posts')) {
+        return Promise.resolve(
+          new Response(JSON.stringify(mockPaginated([noSummary], { totalItems: 1 })), {
+            status: 200,
+            headers: { 'content-type': 'application/json' },
+          }),
+        );
+      }
+      return Promise.resolve(new Response(null, { status: 404 }));
+    }) as typeof fetch);
+    renderScreen(
+      <AuthProvider>
+        <BlogIndex />
+      </AuthProvider>,
+      { initialEntries: ['/blog'] },
+    );
+    await waitFor(() => {
+      expect(screen.getByText('First paragraph of the body.')).toBeInTheDocument();
+    });
+  });
+
   it('renders the empty state when no posts are returned', async () => {
     vi.spyOn(globalThis, 'fetch').mockImplementation(((input: string) => {
       if (input.startsWith('/api/auth/me')) {
diff --git a/specs/api/blog.md b/specs/api/blog.md
index 99072fa..4447190 100644
--- a/specs/api/blog.md
+++ b/specs/api/blog.md
@@ -60,6 +60,7 @@ Standard 404 envelope (per [conventions.md](conventions.md)). Slug-history redir
   "featuredImageUrl": "/api/attachments/blog-posts/civic-tech-roundup-2026/cover.jpg",  // or null — derived from featuredImageKey
   "body": "Markdown source",
   "bodyHtml": "<p>...</p>",            // sanitized HTML, server-rendered
+  "tags": [{ "namespace": "topic", "slug": "transit", "title": "Transit" }, ...],  // tags assigned to the post; [] when none
   "createdAt": "...",
   "updatedAt": "..."
 }