biggus-dickus/docs/superpowers/specs/2026-06-04-frontend-spa-milestone-5-design.md

Frontend SPA — Milestone 5 (Search) — Design

Date: 2026-06-04 Status: Approved (brainstorming) — ready for implementation planning.

Context

Milestones 1–4 (merged to main at 18a19ee) delivered the SPA foundation, object authoring, the publishing workflow, and vocabulary/authority management. The app shell's nav still has two disabled stubs: Search and Fields. Milestone 5 enables Search.

Unlike M2–M4 — which were pure-frontend because the admin endpoints already existed — search has no HTTP endpoint yet. The search crate holds the capability (SearchClient::search(query) -> Vec<ObjectId> against Meilisearch) and on-write index sync is wired at the API layer, but no route exposes querying, and the current method discards everything but the object id. M5 is therefore one combined vertical slice: a backend search endpoint plus the frontend search UI, in a single spec/plan.

Milestone roadmap: M1 foundation → M2 authoring → M3 publish → M4 vocab/authority → M5 search (this). After M5, only the Fields nav stub remains disabled.

Decisions (settled during brainstorming)

• One combined milestone — backend search endpoint + frontend UI together (the frontend is meaningless without the contract, and the backend piece is small).
• Dedicated /search route, two-pane — query + visibility filter + paginated results on the left, the selected object's full detail on the right; mirrors the Objects master–detail layout. The ⌘K global omnibox is deferred to a follow-up.
• Debounced search-as-you-type (~300 ms); q + visibility synced to the URL (replace) so searches are bookmarkable/shareable.
• Visibility filter (All / Draft / Internal / Public) — visibility is already a filterable attribute on the index, and complements the M3 publish workflow.
• Index-backed hits — the endpoint returns hit metadata + a highlighted snippet straight from Meilisearch (no per-hit Postgres round trip / no N+1). The detail pane fetches the full, authoritative record on click. List rows are thus eventually consistent with the DB (acceptable); the detail pane is always fresh.
• "Load more" pagination (useInfiniteQuery), 20 per page, estimated total shown.
• Rich result rows — bold object name; a meta line with object number + a visibility badge; a two-line highlighted snippet.

Backend contract (to build)

search crate

• New serializable types:
  • SearchHit { id: String, object_number: String, object_name: String, brief_description: Option<String>, visibility: String, snippet: Option<String> }
  • SearchResults { hits: Vec<SearchHit>, estimated_total: usize }
• New method SearchClient::search_objects(query: &str, visibility: Option<&str>, offset: usize, limit: usize) -> Result<SearchResults, SearchError>:
  • Meili query: with_query(query), with_offset(offset), with_limit(limit); with_filter("visibility = <v>") only when visibility is Some; attributes_to_highlight + attributes_to_crop (with crop_length) on object_name, brief_description, fields_text.
  • Reads estimated_total_hits (Meili estimatedTotalHits) into estimated_total.
  • Builds snippet from the best _formatted field that actually contains a highlight marker (prefer brief_description, then a matching fields_text entry, then object_name); None if no match context.
• XSS-safe highlighting: Meili is configured with non-HTML sentinel highlight tags — highlight_pre_tag = "\u{2}", highlight_post_tag = "\u{3}" (control chars that cannot occur in catalogue text). The snippet is returned as a plain string carrying these sentinels; the frontend splits on them to render <mark>. No HTML crosses the API boundary, so no dangerouslySetInnerHTML is ever needed.
• The existing thin search(&self, query) -> Vec<ObjectId> is checked for references (insikt find_references): if unused, replace it with search_objects; if used (e.g. a test or CLI), keep it and add search_objects alongside. sync_object / reindex_all / index_object / remove_object are unchanged.

api crate

• New handler module crates/api/src/admin_search.rs: GET /api/admin/search?q=&visibility=&offset=&limit=, auth-required via the AuthUser extractor (same as other admin routes).
  • q: trimmed. Empty q → return SearchResults { hits: [], estimated_total: 0 } without calling Meili.
  • visibility: optional; validated against draft|internal|public (reuse the domain Visibility parse). Invalid value → 400.
  • offset: default 0, ≥ 0; limit: default 20, max 50 (reuse pagination.rs clamping helpers).
  • Search not configured (AppState.search == None) → 503 Service Unavailable.
  • Meili error → 500 (logged via tracing, consistent with the on-write sync logging).
• Returns 200 SearchResults.
• utoipa-annotated (#[utoipa::path(...)]), route registered in admin router and schema registered in crates/api/src/openapi.rs (add SearchHit, SearchResults).

OpenAPI / typed client

• Regenerate web/src/api/schema.d.ts (openapi-typescript) so the typed client gains the /api/admin/search path and the SearchHit / SearchResults component schemas.

Frontend architecture

Routes & navigation

/search             → SearchPage (SearchPanel left, <Outlet/> right)
    index           → SelectSearchPrompt ("Select a result")
    :id             → ObjectDetail (reused unchanged from web/src/objects/)

Added under the protected AppShell group in web/src/app.tsx. In web/src/shell/app-shell.tsx, Search becomes an active NavLink to /search; DISABLED_NAV shrinks to ["fields"].

ObjectDetail is reused as-is: it reads useParams().id, fetches via useObject(id), and its edit link is already absolute (/objects/:id/edit), so editing from a search result navigates into the Objects edit flow correctly.

Components / files

web/src/search/
  search-page.tsx           two-pane grid (grid-cols-[20rem_1fr]); SearchPanel + <Outlet/>
  search-panel.tsx          debounced query <Input>; visibility pills; result count;
                            results list; "Load more"; loading/empty/error states
  search-result-row.tsx     rich row → NavLink to /search/:id (active highlight)
  highlight.tsx             <Highlight text> — splits on the sentinel chars, renders
                            plain segments as text and matched segments as <mark>
  select-search-prompt.tsx  idle detail-pane prompt
web/src/lib/use-debounced-value.ts   generic useDebouncedValue<T>(value, delayMs)
web/src/api/queries.ts      + useSearch(q, visibility)
web/src/app.tsx             + the /search nested route
web/src/shell/app-shell.tsx  enable Search NavLink; DISABLED_NAV = ["fields"]
web/src/i18n/{en,sv}.json   + search.* namespace

Data layer

• useSearch(q: string, visibility: string | null) — useInfiniteQuery:
  • queryKey: ["search", q, visibility]
  • enabled: q.trim().length > 0
  • queryFn({ pageParam = 0 }) → GET /api/admin/search?q=&visibility=&offset=pageParam&limit=20
  • initialPageParam: 0
  • getNextPageParam(lastPage, allPages) → loaded = allPages.flatMap(p => p.hits).length; return loaded < lastPage.estimated_total ? loaded : undefined.
  • Throws on non-200 (a 503/500 surfaces as isError → search.loadError).

URL state

search-panel.tsx owns a controlled input string and the active visibility. A useDebouncedValue of the input (300 ms) drives both useSearch and a useSearchParams write (setSearchParams(..., { replace: true })) for q; the visibility pill writes visibility immediately. Initial state hydrates from the URL on mount so /search?q=bronze&visibility=draft loads pre-populated.

Highlight rendering (highlight.tsx)

<Highlight text={snippet} /> splits text on the sentinel pair (\u{2}…\u{3}) and maps segments to React nodes — plain strings for unmatched text, <mark> for matched spans. Pure string handling; no HTML injection.

Data flow

Type → useDebouncedValue (300 ms) → useSearch(["search", q, visibility]) → GET /api/admin/search → render rich rows from the index payload (no per-hit DB call) → "Load more" fetches next offset and appends → click a row → /search/:id → ObjectDetail fetches the full fresh record via useObject.

Error handling

• Empty q → idle prompt (search.prompt, "Type to search"); no request fired.
• In-flight → loading indicator (skeleton rows, consistent with the Objects list).
• Zero hits → search.empty ("No results").
• Query error or 503 → search.loadError ("Search is unavailable") in the results pane.
• Detail pane retains ObjectDetail's own loading/error/empty behavior.

Testing

Backend

• search crate test against the cms-test-meili container (host port 7701, MEILI_MASTER_KEY=masterKey): seed a few documents, assert search_objects returns matching hits with a non-empty snippet carrying sentinels, that the visibility filter narrows results, that offset/limit page correctly, and that estimated_total is populated.
• api handler tests: unauthenticated → 401; valid query → 200 with results; invalid visibility → 400; limit clamped to 50; search-disabled state → 503.

Frontend (Vitest + RTL + MSW, onUnhandledRequest: "error")

• MSW handler for GET /api/admin/search returning a paged SearchResults fixture (hits with a sentinel-marked snippet; an estimated_total larger than one page).
• Tests: debounced typing issues a request with ?q=; a visibility pill click changes the visibility param and refetches; rows render the object name, object number, a visibility badge, and a <mark> from the snippet; "Load more" appends the next page and hides when exhausted; empty-query idle prompt, zero-results, loading, and error/503 states; clicking a hit navigates to /search/:id; the Search nav item is an enabled link while fields stays disabled.

Project constraints

• en/sv i18n key parity (reuse existing visibility labels where present).
• No any / eslint-disable / @ts-ignore. Codename ban (no "biggus"/"dickus").
• Bundle ≤150 KB gz. Current headroom is ~7 KB; if /search pushes the main chunk over, lazy-load the route with React.lazy + Suspense (as M2 did for the object forms) and re-verify.

Acceptance criteria (Milestone 5 "done")

1. GET /api/admin/search returns index-backed SearchResults (hits + estimated_total), supports q/visibility/offset/limit, is auth-required, returns 503 when search is not configured, and emits XSS-safe (sentinel, non-HTML) highlight snippets.
2. The Search nav item is enabled and routes to /search; debounced typing shows rich result rows with a highlighted snippet, the object number, and a visibility badge.
3. The visibility filter narrows results; the URL reflects q + visibility and is shareable/bookmarkable.
4. "Load more" appends the next page; the estimated total is shown.
5. Clicking a result shows the full, fresh object in the detail pane.
6. Web + backend CI green (cargo test; web typecheck, lint, tests, build, bundle ≤150 KB gz); en/sv parity.

Out of scope / follow-ups

• ⌘K global omnibox / command palette — file a frontend follow-up when M5 lands.
• Richer faceting (object name, owner, has-images, date ranges) and Meili facet distribution counts.
• A public-facing search endpoint (/api/public/search) for an eventual public site.
• Search analytics / query logging.
• Relevance tuning (ranking rules, synonyms, typo tolerance configuration).