jb-website/docs/superpowers/specs/2026-06-01-blog-search-design.md

Blog search — design

Date: 2026-06-01 Status: Approved (pending user spec review) Scope: Add a light, in-page search to /blog that filters the existing archive by keyword.

Goal

Let a reader find a blog post on the /blog index by typing a keyword or short phrase. Match against the post's title, tag, standfirst/description, and body text. Filter the existing year-grouped archive in place.

Non-goals

• Ranking, fuzzy match, excerpt highlighting (upgrade path: Pagefind).
• URL persistence of the query.
• Sitewide / top-bar search.
• Tag-click-to-filter (separate feature).

Approach

A tiny client-side filter implemented as data attributes on each row (no JSON index, no fetch, no React island).

Each rendered post element carries a data-search attribute containing a lowercased, whitespace-collapsed concatenation of its searchable fields. A small inline <script> on the blog index reads the input, tokenizes the query, and toggles a .is-hidden class on every element whose data-search doesn't contain all tokens.

Rejected alternatives:

• Inline JSON index + slug→row mapping: viable but adds a parsing/lookup layer for no real benefit at this scale.
• Fetched /blog/search-index.json: only pays off past ~50 posts; reconsider then.
• Pagefind: full-text engine with ranking; ~70KB+ WASM. Overkill for current archive size. Document as the upgrade path.

Components

New: src/components/molecules/BlogSearch.astro

Renders a single <input type="search"> with a small inline <script> (vanilla JS).

• aria-label="Search posts", placeholder Search the journal….
• Right of the input on focus: a mono Esc to clear hint.
• Width: caps at ~28ch desktop, full-width mobile.
• Styling: font-mono 13px, hairline bottom border using --hairline-on-dark (light/dark variants like existing .tag / .date).

The inline script (~30 lines) does:

1. On input, normalize query: value.toLowerCase().trim().split(/\s+/).filter(Boolean).
2. For each [data-search]: visible iff every token is a substring of its data-search value. Toggle .is-hidden.
3. The featured block (marked data-featured) is itself a [data-search] row, so it filters by the same match check — visible iff it matches the query. (Originally it hid whenever a query was active; changed per docs/superpowers/follow-ups/2026-06-02-blog-search-featured-match.md so featured behaves like any other filterable row.)
4. For each [data-year-head]: count visible siblings until the next year head; hide the head if zero.
5. Toggle a no-results message (<p data-empty>) on/off based on whether any row is visible.
6. Empty query: clear .is-hidden from everything (including featured); hide the no-results message.

Keyboard:

• / anywhere on the page focuses the input (skip if a text input is already focused; check document.activeElement).
• Esc while focused: clear value, blur, restore full archive.
• Enter: no-op (filter is live).

No debouncing — per-keystroke iteration over a few hundred elements is sub-millisecond.

Edited: src/pages/blog/index.astro

• Build searchText per post in the frontmatter: [title, tag, standfirst, description, post.body].filter(Boolean).join(' '), then lowercase, strip markdown punctuation (#*_>\`), and collapse whitespace.
• Mount <BlogSearch /> between .masthead and .feature.
• Add data-featured data-search={featuredSearchText} to the featured <article>.
• Pass searchText to each PostRow.
• Render <p data-empty hidden>No entries match "<span data-empty-query></span>".</p> after .archive, styled like .count (mono 11px, --fg-on-dark-3), aria-live="polite".

Edited: src/components/molecules/PostRow.astro

• Accept a new prop searchText: string.
• Emit data-search={searchText} on the row's root element.

Edited: src/components/molecules/YearHead.astro

• Emit data-year-head on the root element so the script can find heads.

Data flow

Build-time: each post's frontmatter and body are concatenated, normalized, and embedded as a data-search attribute string on the rendered row. No runtime parsing.

Runtime: input event → tokenize → DOM walk → toggle classes. All synchronous. No fetch, no JSON, no async.

CSS

Add to src/pages/blog/index.astro's scoped styles:

.is-hidden { display: none; }

Empty-state <p> reuses the .count style (mono 11px, --fg-on-dark-3).

Accessibility

• Input has aria-label="Search posts".
• Empty-state message has aria-live="polite" so result-count changes are announced.
• .is-hidden uses display: none so hidden content is skipped by assistive tech.
• / shortcut respects existing focus — won't trap users typing elsewhere.

Edge cases

Case	Behavior
Markdown syntax in body	Stripped to plain text before joining; code fence contents kept (useful for searching function names).
Whitespace-only query	Treated as empty: full archive restored.
Tokens with regex-special chars	Safe — only String.includes() is used.
Query matches nothing	No-results message shown; all rows + year heads hidden.
Single-post archive	Featured shows with empty query; a non-empty query keeps the featured (and lone archive entry) visible iff it matches. Acceptable.
JavaScript disabled	Input renders but does nothing; full archive visible. No regression.

Theme parity

Input and empty-state colors follow the existing body.dark / body:not(.dark) pattern used by .tag, .date, .count in the current index.astro. No additions to colors_and_type.css.

Testing

No test harness exists in the repo. Verification is manual via npm run dev:

• Golden path: typing narrows results; year heads collapse when their group empties; clearing restores the full archive.
• Edge cases listed above.
• / keyboard shortcut, Esc clearing.
• Light/dark theme parity.

Upgrade path

If the archive grows past ~50 posts, or readers ask for fuzzy match / ranking / highlighted excerpts, swap this implementation for Pagefind. The BlogSearch component is the only surface that needs to change; the rest of the page is unaffected.