feat(projects): add advanced project filtering & sorting (#181)

[damispicyGithub]

Overview

This PR adds Advanced Project Filtering & Sorting to project discovery. It introduces a public discovery API and a responsive /projects page that lets users filter by budget range, project status, and required skills, sort by newest / budget / deadline, and share or refresh links that preserve the active filters — with debounced requests, loading skeletons, and clear empty states.

Related Issue

Closes #181

Changes

🔎 Project Discovery Service

• [ADD] lib/projectDiscovery.ts
  • Parameterised filters: free-text query (title/description), multi-status, required skills (@> array overlap), and inclusive min/max budget.
  • Whitelisted sorting (created_at, budget, deadline × asc/desc) so no caller-controlled value reaches the SQL identifier position.
  • Single round-trip pagination via COUNT(*) OVER() with a COUNT fallback when the requested page is past the end.
  • Validated query-param parsing with structured ProjectDiscoveryError codes.

🌐 Discovery API

• [ADD] app/api/projects/discover/route.ts
  • GET /api/projects/discover returns { projects, skills, statuses, pagination }.
  • 400 with structured errors on invalid params, 503 on database failure.

🖥️ Discovery UI

• [ADD] components/projects/project-discovery.tsx
  • Responsive layout: sticky filter sidebar on desktop, slide-over filter drawer (Dialog) on mobile.
  • Budget min/max, status checkboxes, multi-select skills, clear-all, and sort select.
  • Debounced (300 ms) requests and URL writes; state hydrates from query params on load.
  • Skeleton loading cards and a reset empty state.
• [ADD] app/projects/page.tsx
  • Server page with a Suspense boundary for useSearchParams.
• [MODIFY] components/navbar.tsx
  • Register "Browse Projects" in the desktop and mobile navigation.

🗄️ Schema

• [ADD] lib/db/migrations/010_project_discovery.sql
  • Idempotently ensures the deadline, skills, and category columns plus indexes for budget, deadline, skills (GIN), and status + recency.

🧪 Tests

• [ADD] __tests__/api/project-discovery.test.ts
  • Coverage for param parsing/validation, row mapping, response shape/pagination, fallback count, and error paths.

Verification Results

pnpm exec vitest run __tests__/api/project-discovery.test.ts
✅ 17/17 passed

pnpm exec eslint lib/projectDiscovery.ts app/api/projects/discover/route.ts app/projects/page.tsx \
  components/projects/project-discovery.tsx components/navbar.tsx __tests__/api/project-discovery.test.ts
✅ no issues

Acceptance Criteria	Status
Responsive filter drawer on mobile	✅ Slide-over Dialog drawer; desktop keeps a sticky sidebar
Loading states while results are fetched	✅ Skeleton cards during requests
Empty states when no projects match	✅ Clear messaging + "Clear all filters" action
Debounced search/filter requests	✅ 300 ms debounce on both fetch and URL sync
Filters persist via URL query parameters	✅ State hydrates from ?q/status/skills/minBudget/maxBudget/sort/order/page
Sorting works consistently	✅ Server-side ORDER BY for newest / budget / deadline
Budget range, status, skills, sort, clear-all	✅ Implemented end-to-end

Note: the new endpoint reads the deadline, skills, and category columns; run pnpm migrate (or npx tsx scripts/migrate.ts) to apply 010_project_discovery.sql before using it.

[drips-wave]

@damispicyGithub Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits