# S04 Research: Trending Searches Homepage Block

## Depth: Light

Straightforward frontend wiring — existing API endpoint → new API client function → new homepage section with CSS.

## Summary

S01 delivered `GET /api/v1/search/popular` returning `{ items: [{query: string, count: number}], cached: bool }` with Redis read-through cache (5-min TTL, 7-day window). The frontend just needs to consume this endpoint and render a "Trending Searches" block on the homepage.

## Requirement Target

- **R035 (active, supporting slice):** Frontend display of popular search terms on homepage. Backend half already delivered by S01.

## Implementation Landscape

### API Client (`frontend/src/api/public-client.ts`)
- **Missing:** No `fetchPopularSearches` function exists yet. Needs adding.
- **Pattern:** Follow existing `fetchStats()` pattern (simple GET, type interface, async function).
- **Types needed:** `PopularSearchItem { query: string; count: number }`, `PopularSearchesResponse { items: PopularSearchItem[]; cached: boolean }` — mirroring backend schemas.

### Homepage (`frontend/src/pages/Home.tsx`)
- **Current sections in order:** Hero search → How It Works → CTA → Popular Topics → Nav Cards → Stats Scorecard → Random Technique → Featured Technique → Recently Added.
- **Placement:** Trending Searches block fits naturally after Stats Scorecard and before Random Technique button — groups the "social proof" signals together (stats + trending).
- **Pattern:** Identical to existing `popularTopics` and `stats` patterns — useState, useEffect with cancellation, conditional render. Already imported: `useEffect`, `useState`, `Link`, `useNavigate`.
- **Graceful degradation:** If endpoint returns empty items or errors, section simply doesn't render (match existing pattern of silently ignoring optional sections).

### Styling (`frontend/src/App.css`)
- **Stats scorecard pattern at line 1456:** Uses `var(--color-bg-surface)`, `var(--color-border)`, `var(--color-accent)`, `var(--color-text-muted)`. Max-width 36rem, centered.
- **Trending block should match:** Same surface background, border radius, centered layout. Terms rendered as clickable pills (navigate to `/search?q=...`) using the existing `pill` class pattern or a new `pill--trending` variant.
- **Popular Topics pattern already in hero:** Uses `pill pill--topic-quick` class on Links. Trending can follow the same pill approach but with distinct styling (e.g., `pill--trending` with a subtle accent border or muted background).

### Backend
- **No changes needed.** Endpoint is deployed and returning data on ub01:8096.

## Recommendation

Single task:
1. Add `PopularSearchItem` / `PopularSearchesResponse` types and `fetchPopularSearches()` to public-client.ts
2. Add state, useEffect, and JSX section to Home.tsx (after stats scorecard, before random button)
3. Add `.home-trending` CSS block matching the scorecard aesthetic — pills are clickable search links
4. Build frontend, deploy to ub01, verify visually

Clicking a trending term should navigate to `/search?q={term}` — same pattern as Popular Topics pills.

## Constraints

- Empty response (no search data yet) → hide section entirely
- Terms should show the query text; count display is optional (showing count may feel metric-heavy alongside the scorecard)
- Keep pill styling consistent with existing design system variables
