hensei-web/docs/search-sidebar-refactor.md

Search Sidebar Refactor Plan (Infinite Scroll + Legacy Parity)

This plan upgrades src/lib/components/panels/SearchSidebar.svelte to support infinite-scrolling search with cancellable requests, modular components, and accessible UX. It also aligns result content with our previous app’s components so we show the most useful fields.

Relevant packages to install: https://runed.dev/docs/getting-started https://runed.dev/docs/utilities/resource

Goals

• Smooth, infinite-scrolling search with debounced input and request cancellation.
• Modular, testable components (header, filters, list, items).
• Strong accessibility and keyboard navigation.
• Reuse legacy field choices for results (image, name, uncap, tags).

Legacy Result Fields (from hensei-web)

Reference: ../hensei-web/components/*Result

• Common
  • Thumbnail (grid variant), localized name.
  • UncapIndicator with FLB/ULB/Transcendence (stage displayed as 5 in old UI).
  • Element tag.
• Weapons
  • Proficiency tag.
• Summons
  • “Subaura” badge (if applicable/available from API).
• Characters
  • Respect special flag for UncapIndicator.
• Implementation
  • Use our image helper (get*Image) and placeholders; do not hardcode paths.

Data Flow

• Unified adapter: searchResource(type, params, { signal }) wraps current resource-specific search functions and normalizes the output to { results, total, nextCursor? }.
• Debounce input: 250–300ms.
• Cancellation: AbortController cancels prior request when query/filters/cursor change.
• Single orchestrating effect: listens to open, type, debouncedQuery, and filters. Resets state and triggers initial fetch.

Infinite Scrolling

• IntersectionObserver sentinel at list bottom triggers loadMore() when visible.
• Guards: isLoading, hasMore, error prevent runaway loads.
• Use Runed's resource() for fetching (Svelte 5‑native) instead of TanStack Query:
  • Reactive key: { type, query: debouncedQuery, filters, page }.
  • Resource fn receives AbortSignal for cancellation.
  • keepPreviousValue: true to avoid flicker on refresh.
  • Append or replace items based on page.

Runed setup

• Install: pnpm add runed
• Import where needed: import { resource } from 'runed'
• No extra config required; works seamlessly with Svelte 5 runes ($state/$derived/$effect).

State Orchestration

• State: items[], isLoading, error, hasMore, page, debouncedQuery, filters, open.
• Reset state on open/type/query/filters change; cancel in-flight; fetch page 1.
• Persist last-used filters per type in localStorage and restore on open.
• Optional lightweight cache: Map<string, { items, page, hasMore, timestamp }> keyed by { type, query, filters } with small TTL.

UX & Accessibility

• Loading skeletons for image/title/badges.
• Error state with Retry and helpful copy.
• Empty state: “No results — try widening filters.”
• Keyboard
  • Focus trap when open; restore focus to trigger on close.
  • Arrow Up/Down to move highlight; Enter to select; Escape to close.
  • aria-live=polite announcements for loading and result counts.
• Performance
  • Pre-fetch next page when 60–70% scrolled (if not using IO sentinel aggressively).
  • Virtualization as a stretch goal if lists become large.

Componentization

• SearchSidebarHeader.svelte: search input (debounced), close button, result count.
• FilterGroup.svelte: Element, Rarity, Proficiency; emits { element?: number[], rarity?: number[], proficiency1?: number[] }.
• Result items (choose either specialized components or generic + slots)
  • WeaponResultItem.svelte: image, name, UncapIndicator, [Element, Proficiency].
  • SummonResultItem.svelte: image, name, UncapIndicator, [Element, Subaura?].
  • CharacterResultItem.svelte: image, name, UncapIndicator(special), [Element].
• ResultList.svelte: renders items, manages sentinel and keyboard focus.
• searchResource.ts: adapter normalizing current API responses.

Normalized API Contract

• Input
  • type: 'weapon' | 'character' | 'summon'
  • query?: string
  • filters: { element?: number[]; rarity?: number[]; proficiency1?: number[] }
  • cursor?: { page?: number; perPage?: number } (or token-ready for future)
  • signal: AbortSignal
• Output
  • { results: any[]; total: number; nextCursor?: { page?: number } }

Tasks (Phased)

Phase 1 — Infra & UX Baseline

• Add searchResource adapter + types; normalize outputs.
• Debounce input and wire AbortController for cancellation.
• Consolidate effects; initialize/reset state predictably.
• Implement infinite scroll via IntersectionObserver; add guards.
• Add skeleton, error, and empty states (minimal styles).

Phase 2 — Componentization & Fields

• Build FilterGroup (Element, Rarity, Proficiency) and emit filters.
• Implement WeaponResultItem, SummonResultItem, CharacterResultItem with fields per legacy.
• Extract SearchSidebarHeader (input, count, close) and ResultList (items + sentinel).

Phase 3 — A11y & Keyboard

• Add focus trap and restore focus on close.
• Apply listbox/option roles; aria-live for loading/count.
• Arrow/Enter/Escape handlers; scroll highlighted item into view.

Phase 4 — Persistence & Performance

• Persist filters per type in localStorage; hydrate on open.
• Optional: add small in-memory cache keyed by { type, query, filters } (TTL 2–5 min).
• Optional: prefetch next page on near-end scroll.
• Optional: list virtualization if needed.

Example: resource() Outline (Runed)

// Debounce query (250–300ms)
let query = $state('')
let debouncedQuery = $state('')
let debounceTimer: any
$effect(() => {
  clearTimeout(debounceTimer)
  debounceTimer = setTimeout(() => (debouncedQuery = query.trim()), 280)
})

// Paging + items
let page = $state(1)
let items: any[] = $state([])
let hasMore = $state(true)

const params = $derived(() => ({ type, query: debouncedQuery, filters, page }))

import { resource } from 'runed'
const searchRes = resource(
  params,
  async (p, ctx) => searchResource(p.type, { query: p.query, filters: p.filters, page: p.page, perPage: 20 }, { signal: ctx.signal }),
  { keepPreviousValue: true }
)

$effect(() => {
  const val = searchRes.value
  if (!val) return
  if (page === 1) items = val.results
  else items = [...items, ...val.results]
  hasMore = val.nextCursor?.page ? true : false // or derive from total_pages
})

// IntersectionObserver sentinel triggers loadMore
function onIntersect() {
  if (!searchRes.loading && hasMore) page += 1
}

Phase 5 — Tests & Polish

• Unit tests for adapter (debounce + abort cases).
• Interaction tests (keyboard nav, infinite scroll, retry/reload).
• Visual QA: confirm result item content matches legacy intent.

Acceptance Criteria

• Infinite scrolling with smooth loading; no duplicate/stale requests.
• Results show image, name, uncap, and tags mirroring legacy components.
• Accessible: screen-reader friendly, keyboard navigable, focus managed.
• Filters and results are modular and easily testable.
• Caching (or local persistence) makes repeat searches feel instant.

Notes / Risks

• svelte-query adds a dependency; keep adapter thin to allow opting in later.
• Subaura badge requires API support; if not present, hide or infer conservatively.
• Virtualization is optional; only implement if list length causes perf issues.

Extending To Teams Explore

The same resource-based, infinite-scroll pattern should power src/routes/teams/explore/+page.svelte to keep UX and tech consistent.

Guidelines:

• Shared primitives
  • Reuse the resource() orchestration, IntersectionObserver sentinel, and list state (items, page, hasMore, isLoading, error).
  • Reuse skeleton, empty, and error components/styles for visual consistency.
  • Optional: extract a tiny use:intersect action and a generic InfiniteList.svelte wrapper.
• Explore adapter
  • Create exploreResource(params, { signal }) that normalizes { results, total, nextCursor } from the teams listing endpoint.
  • Inputs: query?, filters? (element, tags), sort? (newest/popular), page, perPage.
• SSR-friendly
  • +page.server.ts fetches page=1 for SEO and first paint; client continues with infinite scroll.
  • Initialize client state from server data; enable keepPreviousValue to avoid flicker on hydration.
• URL sync
  • Reflect query, filters, sort, and page in search params. On mount, hydrate state from the URL.
  • Improves shareability and back/forward navigation.
• Cards and filters
  • Implement TeamCard.svelte (thumbnail, name/title, owner, likes, updatedAt, element/tags) with a matching skeleton card.
  • Build TeamsFilterGroup.svelte mirroring the sidebar’s FilterGroup.svelte experience.
• Performance
  • Lazy-load images with loading="lazy" and decoding="async"; consider prefetching page+1 on near-end scroll.
  • Virtualization only if card density leads to perf issues.

By following these conventions, the search sidebar and explore page share the same mental model, enabling rapid iteration and less bespoke code per page.