MosswartOverlord/docs/superpowers/specs/2026-07-15-inventory-search-redesign-design.md

Inventory Search redesign — React full-page view

Date: 2026-07-15 Status: Approved (layout + behaviors validated interactively in visual-companion mockup) Mockup: 2026-07-15-inventory-search-redesign-mockup.html (same directory — the approved clickable reference)

Problem

The inventory search UI (static/inventory.html + inventory.js, ~2100 lines of 2010s-era dense gray vanilla HTML) is functionally complete (all filters work against the Go inventory-go service, including the July 2026 spell filters) but visually dated and inconsistent with the React dashboard. Full redesign requested.

Decisions (user-validated)

1. Platform: new full-page view in the existing React app (frontend/), reached via /?view=inventory — same routing pattern as ?view=dashboard in App.tsx.
2. Layout: facet sidebar (direction A of three mocked options) + active- filter chips row borrowed from direction B.
3. Search trigger: instant auto-search, debounced ~400 ms, no Search button; in-flight requests aborted via AbortController.
4. Item details: right-side detail panel opened by row click; ↑/↓ moves selection, Esc closes.
5. Set analysis: dropped entirely. The new page fully replaces inventory.html/inventory.js — both deleted at cutover; the "Analyze Sets" feature ceases to exist.
6. Shareable URLs: filter state serialized to the query string.

Layout (per approved mockup)

• Top bar: title, name/material search box (text param), Reset (clears all filters), column picker (⚙), result count + query time.
• Chips row: one removable chip per active filter; legendary-cantrip chips styled gold (#fc6 on #2a2418).
• Facet sidebar (~210 px, collapsible groups with active-count badges):
  • Characters — searchable checkbox list, All/None/Online links, green online dots (from the /live data the app already polls).
  • Item type — radios: All / Armor / Jewelry / Weapons (+subtype) / Clothing (maps to armor_only/jewelry_only/weapon_only+weapon_type/ clothing_only; shirts/pants reachable as clothing subtypes).
  • Slots — jewelry slots (Ring/Bracelet/Neck/Trinket/Cloak) up front, armor slots behind a "show armor slots" expander (slot_names CSV).
  • Cantrips — find-as-you-type filter over the legendary cantrip list, grouped (Attributes / Skills / Defense / Banes / Other); checked items pin to a "Selected" section on top; gold styling; plus an "any-tier spell search" text input (spell_contains). Checkbox values = the same display names the old page sent (legendary_cantrips CSV, AND semantics).
  • Ratings (collapsed) — min inputs for the 4 common ratings, "all 20 ratings" expander for the rest (min_* params).
  • Equipment sets (collapsed) — searchable set list (item_set/item_sets).
  • Item state (collapsed) — equipped-only, bonded, attuned, rare (equipment_status, bonded, attuned, is_rare).
  • Reqs & value (collapsed) — wield level ≤, value ≥, workmanship ≥, burden ≤ (max_level, min_value, min_workmanship, max_burden).
• Results table: server-side sort via sort_by/sort_dir (click headers); sticky header; equipped marker (green ⚔); Spells column with legendary names gold; pagination footer (200/page default, page/limit). Column set togglable via the ⚙ picker, persisted to localStorage.
• Detail panel (~250 px): item name, slot, equipped state, character, value/burden/wield/workmanship/mana, full ordered spell list (legendary gold). Keyboard: ↑/↓/Esc.

Implementation shape

• No backend changes. The existing GET /api/inv/search/items supports every filter above (validated; the spell filters shipped 2026-07-14).
• New directory frontend/src/components/inventory/:
  • InventorySearchPage.tsx — page layout, keyboard handling.
  • FilterSidebar.tsx + one small component per filter group.
  • ActiveChips.tsx, ResultsTable.tsx, DetailPanel.tsx.
  • useInventorySearch.ts — single-reducer filter state, debounce, AbortController fetch, URL (de)serialization.
• Filter state ↔ URL: serialize non-default filters into query params on change (replaceState), parse on mount — bookmarkable searches.
• Styling: frontend/src/styles/inventory.css, .inv-* class prefix, dashboard dark tokens (#111 bg, #1a1a1a panels, #333 borders, #88f accent, #fc6 legendary gold, Segoe UI) — mirrors map-layout.css conventions.
• No new npm dependencies.
• Cantrip list + grouping: lift the value strings from the old inventory.html checkbox grid (they are the strings the backend matches); store as a typed constant module.
• Character list: reuse the app's existing live-players data source for names
  • online status; fall back to /api/inv/characters/list for characters that are offline/never online.

Cutover

Same commit series: add the new view → repoint the dashboard tool-link that currently opens /inventory.html to /?view=inventory → delete static/inventory.html and static/inventory.js. /inventory.html then 404s to the SPA fallback; acceptable (single-user tool, no external links).

Testing & verification

The frontend has no test framework (build = tsc -b && vite build). Verification per task: TypeScript build green + live checks in the Vite dev server against the production API, then post-deploy spot checks of the same scenarios used for the spell-filter validation (Invuln+Summon → 2 items; Ring+Invuln → 56; filterless jewelry → ~4.8k). Adding a test harness is out of scope.

Deploy

bash deploy-frontend.sh (builds + copies into static/), commit static/

• frontend/ + deletions, push; server picks it up via bind mount, no restart.

Out of scope

• Set analysis (dropped per decision 5).
• Suitbuilder page (untouched).
• React-window (InventoryWindow.tsx) per-character inventory — unrelated.
• Mobile layout (desktop tool); no test framework introduction.