# Blog Search 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:** Add a light, in-page keyword/topic filter to `/blog` that narrows the year-grouped archive as the reader types.

**Architecture:** Tiny client-side filter implemented as `data-search` attributes on each row + featured block. A small inline vanilla-JS script in a new `BlogSearch.astro` component tokenizes the query, toggles `.is-hidden` on rows whose `data-search` doesn't contain every token, hides empty year heads, and toggles a no-results message. No JSON index, no fetch, no React island, no new dependencies.

**Tech Stack:** Astro 5 content collections, Astro components (`.astro`), scoped CSS, vanilla JS.

**Source spec:** `docs/superpowers/specs/2026-06-01-blog-search-design.md`

**Verification note:** This repo has no automated test harness, and the spec deliberately doesn't add one. Each task ends with a manual verification step using the Astro dev server (`npm run dev` → http://localhost:4321/blog) and/or grep/curl against the rendered HTML. Confirm the verification passes before committing.

---

## File map

| File | Action | Responsibility |
|---|---|---|
| `src/components/molecules/PostRow.astro` | modify | Accept `searchText` prop, emit `data-search` on root anchor |
| `src/components/molecules/YearHead.astro` | modify | Emit `data-year-head` on root |
| `src/pages/blog/index.astro` | modify | Build `searchText` per post; wire to `PostRow` + featured `<article>`; render `<BlogSearch />` and the empty-state `<p>`; add `.is-hidden` rule |
| `src/components/molecules/BlogSearch.astro` | create | Input, styles, and the filter script (including keyboard shortcuts) |

---

## Task 1: `PostRow` accepts and emits `data-search`

**Files:**
- Modify: `src/components/molecules/PostRow.astro`

- [ ] **Step 1: Add the `searchText` prop and emit it on the root anchor**

Edit `src/components/molecules/PostRow.astro` — change the frontmatter and the `<a>` tag:

```astro
---
interface Props {
  date: string;
  title: string;
  href: string;
  deck?: string;
  tag?: string;
  searchText: string;
}

const { date, title, href, deck, tag, searchText } = Astro.props;
---

<a class="postrow" href={href} data-search={searchText}>
  <span class="pdate">{date}</span>
  <span class="middle">
    <span class="pttl">{title}<span class="tick"></span></span>
    {deck && <span class="pdek">{deck}</span>}
  </span>
  {tag && <span class="ptag">{tag}</span>}
</a>
```

Leave the `<style>` block unchanged.

- [ ] **Step 2: Verify the build still type-checks**

Run: `npx astro check`
Expected: One or more errors about `src/pages/blog/index.astro` not passing `searchText` to `<PostRow>`. That's the only failure — it confirms the prop is now required and will be supplied in Task 3. If you see errors anywhere other than `blog/index.astro`, stop and investigate.

- [ ] **Step 3: Commit**

```bash
git add src/components/molecules/PostRow.astro
git commit -m "feat(blog): PostRow accepts searchText, emits data-search"
```

---

## Task 2: `YearHead` emits `data-year-head`

**Files:**
- Modify: `src/components/molecules/YearHead.astro`

- [ ] **Step 1: Add the attribute**

In `src/components/molecules/YearHead.astro`, change the root `<div>`:

```astro
<div class="yearhead" data-year-head>
  <span class="yr">{year}</span>
  <span class="ln"></span>
  <span class="n">{formatted}</span>
</div>
```

Nothing else changes.

- [ ] **Step 2: Verify**

Run: `npm run build 2>&1 | tail -20`
Expected: Build still fails at `blog/index.astro` (PostRow searchText). No new errors. (You can also `grep -R "data-year-head" src/` to confirm the attribute is present in source.)

- [ ] **Step 3: Commit**

```bash
git add src/components/molecules/YearHead.astro
git commit -m "feat(blog): YearHead emits data-year-head for filter targeting"
```

---

## Task 3: Build `searchText` in blog index frontmatter and wire it through

**Files:**
- Modify: `src/pages/blog/index.astro`

- [ ] **Step 1: Add the `buildSearchText` helper and compute per-post search text in the frontmatter**

In `src/pages/blog/index.astro`, after the imports and before the `posts.sort(...)` line, add the helper. Then build a `Map<id, string>` keyed by post id.

Replace the existing frontmatter block (the section between the two `---` fences) with:

```astro
---
import BaseLayout from "~/layouts/BaseLayout.astro";
import Eyebrow from "~/components/atoms/Eyebrow.astro";
import Mark from "~/components/atoms/Mark.astro";
import PostRow from "~/components/molecules/PostRow.astro";
import YearHead from "~/components/molecules/YearHead.astro";
import InkArrow from "~/components/atoms/InkArrow.astro";
import BlogSearch from "~/components/molecules/BlogSearch.astro";
import { blog } from "~/lib/urls";
import { getCollection } from "astro:content";

const posts = await getCollection("posts", ({ data }) => !data.draft);
posts.sort((a, b) => b.data.date.getTime() - a.data.date.getTime());

const [featured, ...rest] = posts;

const dateFmtMonthYear = new Intl.DateTimeFormat("en-AU", { month: "short", year: "numeric" });
const dateFmtMonthYearLong = new Intl.DateTimeFormat("en-AU", { month: "long", year: "numeric" });

// Group the archive by year.
const byYear = new Map<number, typeof rest>();
for (const post of rest) {
  const year = post.data.date.getFullYear();
  const bucket = byYear.get(year) ?? [];
  bucket.push(post);
  byYear.set(year, bucket);
}
const yearGroups = Array.from(byYear.entries()).sort(([a], [b]) => b - a);

// Build the per-post `data-search` string at build time. We concatenate the
// searchable fields, lowercase, strip a small set of markdown punctuation, and
// collapse whitespace. Body text is the raw markdown from the content
// collection entry's `.body` property — MDX expressions that survive end up as
// literal text, which is harmless for substring matching.
function buildSearchText(post: (typeof posts)[number]): string {
  const parts = [
    post.data.title,
    post.data.tag,
    post.data.standfirst,
    post.data.description,
    post.body ?? "",
  ].filter(Boolean) as string[];
  return parts
    .join(" ")
    .toLowerCase()
    .replace(/[#*_>`\[\]()]/g, " ")
    .replace(/\s+/g, " ")
    .trim();
}

const searchTextById = new Map<string, string>();
for (const post of posts) {
  searchTextById.set(post.id, buildSearchText(post));
}
---
```

The only new things vs. the existing file: the `BlogSearch` import, the `buildSearchText` function, and the `searchTextById` map. Leave the body of the component (everything after the second `---`) untouched in this task.

- [ ] **Step 2: Pass `searchText` to each `<PostRow>` and add `data-search` + `data-featured` on the featured `<article>`**

Still in `src/pages/blog/index.astro`, locate the `<article class="feature">` line and add the two attributes:

```astro
<article class="feature" data-featured data-search={searchTextById.get(featured.id) ?? ""}>
```

Then locate the `<PostRow ... />` invocation inside `yearGroups.map(...)` and add the prop:

```astro
<PostRow
  date={dateFmtMonthYear.format(post.data.date)}
  title={post.data.title}
  href={blog(`/posts/${post.id}/`)}
  deck={post.data.standfirst}
  tag={post.data.tag}
  searchText={searchTextById.get(post.id) ?? ""}
/>
```

- [ ] **Step 3: Add `<BlogSearch />` placeholder import target**

Astro will fail to import `BlogSearch` until Task 4 creates it. To unblock incremental verification, create a stub file now and replace its contents in Task 4. Create `src/components/molecules/BlogSearch.astro` containing exactly:

```astro
---
// Stub — real implementation lands in Task 4.
---
```

- [ ] **Step 4: Verify the build succeeds and `data-search` appears in the output**

Run: `npm run build 2>&1 | tail -20`
Expected: Build succeeds (no errors).

Run: `grep -c 'data-search="' dist/blog/index.html`
Expected: `4` (one for the featured `<article>` plus one for each of the three current posts). If the count is off, the wiring is wrong — fix before continuing.

Run: `grep -c 'data-year-head' dist/blog/index.html`
Expected: `≥ 1` (one per year group; current posts span 1+ years).

- [ ] **Step 5: Commit**

```bash
git add src/pages/blog/index.astro src/components/molecules/BlogSearch.astro
git commit -m "feat(blog): build per-post searchText, wire to PostRow and featured"
```

---

## Task 4: Render the `<BlogSearch />` input (markup + styles, no script yet)

**Files:**
- Modify: `src/components/molecules/BlogSearch.astro` (replace the stub)
- Modify: `src/pages/blog/index.astro` (mount the component and add the empty-state element + `.is-hidden` rule)

- [ ] **Step 1: Write the component markup and scoped styles**

Replace the entire contents of `src/components/molecules/BlogSearch.astro` with:

```astro
---
// Light client-side filter for the blog archive.
// Reads [data-search] attributes on rows + the featured article, hides
// non-matches, collapses empty year heads, toggles a no-results message.
// Filter script is added in Task 5; this file ships markup + styles only.
---

<div class="bsearch">
  <input
    type="search"
    class="bsearch__input"
    aria-label="Search posts"
    placeholder="Search the journal…"
    autocomplete="off"
    spellcheck="false"
  />
  <span class="bsearch__hint" aria-hidden="true">Esc to clear</span>
</div>

<style>
  .bsearch {
    display: flex;
    align-items: baseline;
    gap: 14px;
    padding: clamp(14px, 2.4vh, 22px) 0;
    border-top: 1px solid var(--hairline-on-dark);
    border-bottom: 1px solid var(--hairline-on-dark);
  }
  :global(body:not(.dark)) .bsearch {
    border-top-color: var(--hairline);
    border-bottom-color: var(--hairline);
  }
  .bsearch__input {
    flex: 1;
    max-width: 28ch;
    background: transparent;
    border: 0;
    border-bottom: 1px solid transparent;
    padding: 6px 0;
    font-family: var(--font-mono);
    font-size: 13px;
    color: var(--fg-on-dark-1);
    letter-spacing: 0.02em;
    outline: none;
    transition: border-color var(--dur-base) var(--ease-out);
  }
  :global(body:not(.dark)) .bsearch__input {
    color: var(--fg-1);
  }
  .bsearch__input::placeholder {
    color: var(--fg-on-dark-3);
  }
  :global(body:not(.dark)) .bsearch__input::placeholder {
    color: var(--fg-3);
  }
  .bsearch__input:focus {
    border-bottom-color: var(--accent);
  }
  .bsearch__hint {
    font-family: var(--font-mono);
    font-size: 11px;
    color: var(--fg-on-dark-3);
    letter-spacing: 0.06em;
    opacity: 0;
    transition: opacity var(--dur-base) var(--ease-out);
  }
  :global(body:not(.dark)) .bsearch__hint {
    color: var(--fg-3);
  }
  .bsearch:focus-within .bsearch__hint {
    opacity: 1;
  }

  @media (max-width: 800px) {
    .bsearch__input {
      max-width: none;
    }
    .bsearch__hint {
      display: none;
    }
  }
</style>
```

- [ ] **Step 2: Mount the component and add the empty-state element + `.is-hidden` rule in the blog index**

In `src/pages/blog/index.astro`:

(a) Inside the `<BaseLayout>` body, place `<BlogSearch />` between the closing `</header>` of `.masthead` and the `{featured && (...)}` block. The resulting structure should look like:

```astro
  <header class="masthead">
    {/* ...unchanged... */}
  </header>

  <BlogSearch />

  {
    featured && (
      <article class="feature" data-featured data-search={searchTextById.get(featured.id) ?? ""}>
        {/* ...unchanged... */}
      </article>
    )
  }
```

(b) After the closing `</section>` of `.archive`, add the empty-state paragraph:

```astro
  <p class="empty" data-empty hidden aria-live="polite">
    No entries match “<span data-empty-query></span>”.
  </p>
```

(c) Inside the existing `<style>` block in `index.astro`, add two rules at the end (just before the closing `</style>`):

```css
  .is-hidden { display: none !important; }

  .empty {
    font-family: var(--font-mono);
    font-size: 11px;
    letter-spacing: 0.08em;
    color: var(--fg-on-dark-3);
    margin: clamp(28px, 5vh, 52px) 0 0;
    font-feature-settings: "onum" 1;
  }
  :global(body:not(.dark)) .empty { color: var(--fg-3); }
```

(The `!important` on `.is-hidden` defends against any future row-level `display` rule overriding it.)

- [ ] **Step 3: Verify the build and visual placement**

Run: `npm run build 2>&1 | tail -10`
Expected: Build succeeds.

Run: `grep -c 'class="bsearch"' dist/blog/index.html`
Expected: `1`.

Run: `grep -c 'data-empty' dist/blog/index.html`
Expected: `2` (the `<p data-empty>` and the inner `<span data-empty-query>`).

Run: `npm run dev` (background), open http://localhost:4321/blog, confirm the search input renders between the masthead and the featured article and looks at home with the rest of the page. Typing has no effect yet — that's expected. Then stop the dev server.

- [ ] **Step 4: Commit**

```bash
git add src/components/molecules/BlogSearch.astro src/pages/blog/index.astro
git commit -m "feat(blog): render search input, empty-state, hidden utility"
```

---

## Task 5: Add the filter script to `BlogSearch`

**Files:**
- Modify: `src/components/molecules/BlogSearch.astro`

- [ ] **Step 1: Append the `<script>` block**

At the end of `src/components/molecules/BlogSearch.astro` (after the closing `</style>`), append the filter script. Astro hoists `<script>` blocks and bundles them; this is the canonical way to ship per-component JS.

```astro
<script>
  // Lives on /blog. No-ops gracefully on any other page (selectors return empty).
  const input = document.querySelector<HTMLInputElement>(".bsearch__input");
  if (input) {
    const rows = Array.from(
      document.querySelectorAll<HTMLElement>("[data-search]")
    );
    const featured = document.querySelector<HTMLElement>("[data-featured]");
    const yearHeads = Array.from(
      document.querySelectorAll<HTMLElement>("[data-year-head]")
    );
    const empty = document.querySelector<HTMLElement>("[data-empty]");
    const emptyQuery = empty?.querySelector<HTMLElement>("[data-empty-query]");

    function applyFilter() {
      const raw = input!.value.toLowerCase().trim();
      const tokens = raw.length ? raw.split(/\s+/) : [];
      const isFiltering = tokens.length > 0;

      let visibleCount = 0;
      for (const row of rows) {
        const haystack = row.dataset.search ?? "";
        const isFeatured = row === featured;
        let visible: boolean;
        if (!isFiltering) {
          visible = true;
        } else if (isFeatured) {
          // Featured hides whenever there's a query, regardless of match.
          visible = false;
        } else {
          visible = tokens.every((t) => haystack.includes(t));
        }
        row.classList.toggle("is-hidden", !visible);
        if (visible && !isFeatured) visibleCount += 1;
      }

      // Hide year heads whose following rows are all hidden.
      for (const head of yearHeads) {
        let anyVisible = false;
        let node: Element | null = head.nextElementSibling;
        while (node && !node.matches("[data-year-head]")) {
          if (node.matches("[data-search]") && !node.classList.contains("is-hidden")) {
            anyVisible = true;
            break;
          }
          node = node.nextElementSibling;
        }
        head.classList.toggle("is-hidden", !anyVisible);
      }

      // Toggle empty-state message.
      if (empty) {
        const showEmpty = isFiltering && visibleCount === 0;
        empty.hidden = !showEmpty;
        if (showEmpty && emptyQuery) emptyQuery.textContent = input!.value.trim();
      }
    }

    input.addEventListener("input", applyFilter);
  }
</script>
```

A few notes for the engineer:

- The script runs once at module-evaluation time after the DOM is parsed (Astro hoists `<script>` to the page `<head>` with `type="module"`, which defers execution). No `DOMContentLoaded` guard is needed.
- `row.dataset.search` is already lowercased at build time, so we only lowercase the query.
- The year-head walk stops at the next `[data-year-head]` or end-of-siblings, so it correctly scopes per group.
- The `[data-search]` selector picks up both the featured `<article>` and the post rows; the `isFeatured` branch handles them differently.

- [ ] **Step 2: Verify by typing in the dev server**

Run: `npm run dev` (background), open http://localhost:4321/blog.

Type these queries and confirm:
- empty → masthead + featured + full archive visible, no empty-state.
- `the` (likely matches multiple posts) → featured hides, only matching rows remain, year heads visible only above visible rows.
- `xxxxx-no-match` → featured hides, every row hides, year heads all hide, empty-state appears with the query in quotes.
- Backspace to empty → original layout restored exactly.

Use the browser devtools' Elements panel to verify `.is-hidden` is being toggled (not `style="display:none"`).

Stop the dev server.

- [ ] **Step 3: Commit**

```bash
git add src/components/molecules/BlogSearch.astro
git commit -m "feat(blog): live in-page filter via data-search attributes"
```

---

## Task 6: Keyboard shortcuts (`/` to focus, `Esc` to clear)

**Files:**
- Modify: `src/components/molecules/BlogSearch.astro`

- [ ] **Step 1: Extend the script with two global key handlers**

In `src/components/molecules/BlogSearch.astro`, inside the existing `if (input) { ... }` block, **after** the `input.addEventListener("input", applyFilter);` line, append:

```ts
    // `/` from anywhere on the page focuses the search input — unless the user
    // is already typing somewhere editable (text input, textarea, or any
    // contenteditable element). `Esc` while the input is focused clears the
    // query, blurs, and restores the full archive.
    document.addEventListener("keydown", (event) => {
      if (event.key === "/" && !event.metaKey && !event.ctrlKey && !event.altKey) {
        const target = event.target as HTMLElement | null;
        const tag = target?.tagName;
        const editable =
          tag === "INPUT" ||
          tag === "TEXTAREA" ||
          target?.isContentEditable === true;
        if (!editable) {
          event.preventDefault();
          input!.focus();
        }
      } else if (event.key === "Escape" && document.activeElement === input) {
        if (input!.value !== "") {
          input!.value = "";
          applyFilter();
        }
        input!.blur();
      }
    });
```

- [ ] **Step 2: Verify keyboard behavior**

Run: `npm run dev` (background), open http://localhost:4321/blog.

- Press `/` while focus is on the page body → input gains focus, the `/` character is **not** inserted into the input (the `preventDefault()` blocks it).
- Click into the input, type `foo`, press `Esc` → input clears, blurs, archive restored.
- Click into the input, leave it empty, press `Esc` → input blurs (no harm done).
- Focus the input, type `/` → the `/` should appear in the input (because the editable check skips the shortcut). Clear it.
- Press `Cmd+/` or `Ctrl+/` → no focus change (the modifier check blocks it; the browser may show its own shortcut, which is fine).

Stop the dev server.

- [ ] **Step 3: Commit**

```bash
git add src/components/molecules/BlogSearch.astro
git commit -m "feat(blog): / focuses search, Esc clears and blurs"
```

---

## Task 7: Final manual verification pass

**Files:** none changed; this task is verification only. Do not commit unless a fix surfaces.

- [ ] **Step 1: Production-build check**

Run: `npm run build`
Expected: Succeeds with no errors. Look at the printed bundle sizes — the new JS should be well under 2KB (gzipped reported by Astro).

- [ ] **Step 2: Preview the production build and walk the edge cases**

Run: `npm run preview` (background), open http://localhost:4321/blog.

Walk through each item from the spec's edge-cases table:

- **Markdown syntax in body**: Search for a word you know is inside backticks or near `**bold**` in a post body. It should still match.
- **Whitespace-only query**: Type ` ` (one space) → archive fully restored, no empty-state.
- **Regex-special characters**: Type `(` then `)` then `*` → no JS error, no matches (or harmless substring matches).
- **Single-post / zero-result archive**: Type a query that matches nothing → featured hides, all rows hide, year heads hide, empty-state visible with the typed query rendered between curly quotes.
- **Featured filter behavior**: Type any non-empty query → featured `<article>` is always hidden, even if its content matches.
- **Year head collapse**: Type a query that matches posts in only one year → year heads for empty years should be hidden.
- **JS-disabled fallback**: In devtools, disable JavaScript and reload. Input renders but does nothing; archive is fully visible. No console errors. Re-enable JS.

- [ ] **Step 3: Light/dark theme parity**

If the site exposes a way to toggle the `body.dark` class (devtools → Elements → toggle the class), do so and confirm:
- Input border, placeholder colour, hint colour, and empty-state colour all flip correctly.
- No element renders in an obviously wrong colour in either mode.

- [ ] **Step 4: Keyboard accessibility**

- Tab through the page from the top; the input is reachable in document order.
- Screen-reader announcement isn't directly testable without VO/NVDA, but confirm in DevTools that the input has `aria-label="Search posts"` and the empty-state `<p>` has `aria-live="polite"`.

- [ ] **Step 5: Stop the preview server**

If everything above checks out, the feature is done. If anything fails, fix it in a new commit and re-run this task before reporting complete.

---

## Done

After Task 7 passes, the implementation matches the spec. Suggested follow-up message to the user:

> Blog search is in. Run `npm run dev` and try `/` to focus, `Esc` to clear. If you decide later to scale beyond ~50 posts or want fuzzy match / ranking / excerpt highlighting, the swap-in is Pagefind — the only file that needs to change is `BlogSearch.astro`.