feat: Add SortDropdown server-side integration with URL-synced sort params (closes #259)

Author: emdevelopa

backend/src/index.ts

@@ -18,6 +18,7 @@ import {
   calculateProgress,
   CampaignProgress,
   CampaignRecord,
+  CampaignSortField,
   CampaignStatus,
   claimCampaign,
   createCampaign,
@@ -32,6 +33,7 @@ import {
   type ListCampaignsOptions,
   reconcileOnChainPledge,
   refundContributor,
+  SortOrder,
   updateCampaign,
 } from './services/campaignStore';
 import { checkDbHealth } from './services/db';
@@ -201,18 +203,28 @@ export function parseCampaignListFilters(query: {
   q?: unknown;
   search?: unknown;
   includeDeleted?: unknown;
+  sort?: unknown;
+  order?: unknown;
 }): {
   asset?: string;
   status?: CampaignStatus;
   searchQuery?: string;
   includeDeleted?: boolean;
+  sort?: CampaignSortField;
+  order?: SortOrder;
 } {
+  const VALID_SORT_FIELDS: CampaignSortField[] = ['newest', 'deadline', 'percentFunded', 'totalPledged'];
+  const VALID_ORDERS: SortOrder[] = ['asc', 'desc'];
+  const rawSort = normalizeQueryValue(query.sort);
+  const rawOrder = normalizeQueryValue(query.order);
   return {
     asset: normalizeAssetFilter(query.asset),
     status: normalizeStatusFilter(query.status),
     searchQuery:
       normalizeQueryValue(query.search) || normalizeQueryValue(query.q),
     includeDeleted: query.includeDeleted === "true",
+    sort: rawSort && VALID_SORT_FIELDS.includes(rawSort as CampaignSortField) ? (rawSort as CampaignSortField) : undefined,
+    order: rawOrder && VALID_ORDERS.includes(rawOrder as SortOrder) ? (rawOrder as SortOrder) : undefined,
   };
 }
 
@@ -261,13 +273,17 @@ app.get('/api/campaigns', (req: Request, res: Response) => {
     q: req.query.q,
     search: req.query.search,
     includeDeleted: req.query.includeDeleted,
+    sort: req.query.sort,
+    order: req.query.order,
   });
 
   const listOptions: ListCampaignsOptions = {
     searchQuery: filters.searchQuery,
     assetCode: filters.asset,
     status: filters.status,
     includeDeleted: filters.includeDeleted,
+    sort: filters.sort,
+    order: filters.order,
   };
   if (paginationResult.page !== undefined) {
     listOptions.page = paginationResult.page;

backend/src/services/campaignStore.ts

@@ -272,13 +272,18 @@ export function calculateProgress(campaign: CampaignRecord, at = nowInSeconds())
   };
 }
 
+export type CampaignSortField = 'newest' | 'deadline' | 'percentFunded' | 'totalPledged';
+export type SortOrder = 'asc' | 'desc';
+
 export interface ListCampaignsOptions {
   searchQuery?: string;
   assetCode?: string;
   status?: CampaignStatus;
   includeDeleted?: boolean;
   page?: number;
   limit?: number;
+  sort?: CampaignSortField;
+  order?: SortOrder;
 }
 
 export interface ListCampaignsResult {
@@ -383,9 +388,30 @@ export function listCampaigns(options?: ListCampaignsOptions): ListCampaignsResu
   const countQuery = `SELECT COUNT(DISTINCT campaigns.id) as total FROM campaigns LEFT JOIN pledges ON campaigns.id = pledges.campaign_id AND pledges.refunded_at IS NULL${whereClause}`;
   const totalCount = (db.prepare(countQuery).get(...params) as { total: number }).total;
 
+  // Build ORDER BY clause from sort options
+  const sortField = options?.sort ?? 'newest';
+  const sortOrder = options?.order ?? 'desc';
+  const orderDir = sortOrder === 'asc' ? 'ASC' : 'DESC';
+  let orderByClause: string;
+  switch (sortField) {
+    case 'deadline':
+      orderByClause = `campaigns.deadline ${sortOrder === 'desc' ? 'DESC' : 'ASC'}`;
+      break;
+    case 'percentFunded':
+      orderByClause = `(CAST(campaigns.pledged_amount AS REAL) / CAST(campaigns.target_amount AS REAL)) ${orderDir}`;
+      break;
+    case 'totalPledged':
+      orderByClause = `campaigns.pledged_amount ${orderDir}`;
+      break;
+    case 'newest':
+    default:
+      orderByClause = `campaigns.created_at ${orderDir}`;
+      break;
+  }
+
   const dataQuery = paginate
-    ? `SELECT campaigns.*, COUNT(pledges.id) as pledge_count FROM campaigns LEFT JOIN pledges ON campaigns.id = pledges.campaign_id AND pledges.refunded_at IS NULL${whereClause} GROUP BY campaigns.id ORDER BY campaigns.created_at DESC LIMIT ? OFFSET ?`
-    : `SELECT campaigns.*, COUNT(pledges.id) as pledge_count FROM campaigns LEFT JOIN pledges ON campaigns.id = pledges.campaign_id AND pledges.refunded_at IS NULL${whereClause} GROUP BY campaigns.id ORDER BY campaigns.created_at DESC`;
+    ? `SELECT campaigns.*, COUNT(pledges.id) as pledge_count FROM campaigns LEFT JOIN pledges ON campaigns.id = pledges.campaign_id AND pledges.refunded_at IS NULL${whereClause} GROUP BY campaigns.id ORDER BY ${orderByClause} LIMIT ? OFFSET ?`
+    : `SELECT campaigns.*, COUNT(pledges.id) as pledge_count FROM campaigns LEFT JOIN pledges ON campaigns.id = pledges.campaign_id AND pledges.refunded_at IS NULL${whereClause} GROUP BY campaigns.id ORDER BY ${orderByClause}`;
 
   const rows = (
     paginate

frontend/src/App.tsx

@@ -1,5 +1,5 @@
 import { useEffect, useMemo, useRef, useState } from "react";
-import { useNavigate, useParams } from "react-router-dom";
+import { useNavigate, useParams, useSearchParams } from "react-router-dom";
 import { CampaignDetailPanel } from "./components/CampaignDetailPanel";
 import { ErrorBoundary } from "./components/ErrorBoundary";
 import { FundedConfetti } from "./components/FundedConfetti";
@@ -123,6 +123,9 @@ function App() {
   const [hasMoreCampaigns, setHasMoreCampaigns] = useState(false);
   const [isLoadingMoreCampaigns, setIsLoadingMoreCampaigns] = useState(false);
   const activeSearchRef = useRef("");
+  const activeSortRef = useRef<string>('newest');
+  const activeOrderRef = useRef<string>('desc');
+  const [searchParams] = useSearchParams();
   const [issues, setIssues] = useState<OpenIssue[]>([]);
   const [history, setHistory] = useState<CampaignEvent[]>([]);
   const [appConfig, setAppConfig] = useState<AppConfig | null>(null);
@@ -169,11 +172,15 @@ function App() {
     page: number,
     searchQuery = "",
     append = false,
+    sort = activeSortRef.current,
+    order = activeOrderRef.current,
   ): Promise<Awaited<ReturnType<typeof listCampaigns>>> {
     const response = await listCampaigns({
       search: searchQuery,
       page,
       limit: CAMPAIGN_PAGE_SIZE,
+      sort,
+      order,
     });
 
     setCampaigns((current) => (append ? [...current, ...response.data] : response.data));
@@ -729,6 +736,11 @@ function App() {
             onSearchChange={(query) => {
               void refreshCampaigns(query);
             }}
+            onSortChange={(sort, order) => {
+              activeSortRef.current = sort;
+              activeOrderRef.current = order;
+              void refreshCampaigns(activeSearchRef.current);
+            }}
             onLoadMore={() => {
               void loadMoreCampaigns();
             }}

frontend/src/components/CampaignsTable.tsx

@@ -1,6 +1,7 @@
 import { LayoutGrid } from "lucide-react";
 import { useEffect, useMemo, useRef, useState } from "react";
 import { useDebounce } from "../hooks/useDebounce";
+import { useSearchParams } from "react-router-dom";
 import { Campaign, CampaignStatus } from "../types/campaign";
 import { EmptyState } from "./EmptyState";
 import { AssetFilterDropdown } from "./AssetFilterDropdown";
@@ -30,6 +31,7 @@ interface CampaignsTableProps {
   selectedCampaignId: string | null;
   onSelect: (campaignId: string) => void;
   onSearchChange?: (query: string) => void;
+  onSortChange?: (sort: SortOption, order: 'asc' | 'desc') => void;
   onLoadMore?: () => void;
   hasMore?: boolean;
   isLoadingMore?: boolean;
@@ -64,19 +66,36 @@ export function CampaignsTable({
   selectedCampaignId,
   onSelect,
   onSearchChange,
+  onSortChange,
   onLoadMore,
   hasMore = false,
   isLoadingMore = false,
   isLoading = false,
   invalidUrlCampaignId = null,
 }: CampaignsTableProps) {
+  const [searchParams, setSearchParams] = useSearchParams();
+  const urlSort = (searchParams.get('sort') as SortOption | null) ?? 'newest';
+  const urlOrder = (searchParams.get('order') as 'asc' | 'desc' | null) ?? 'desc';
+  const VALID_SORTS: SortOption[] = ['newest', 'deadline', 'percentFunded', 'totalPledged'];
+  const sortBy: SortOption = VALID_SORTS.includes(urlSort) ? urlSort : 'newest';
   const [assetCode, setAssetCode] = useState("");
   const [statusFilter, setStatusFilter] = useState<StatusFilterValue>("");
-  const [sortBy, setSortBy] = useState<SortOption>("newest");
   const [searchQuery, setSearchQuery] = useState("");
   const loadMoreRef = useRef<HTMLDivElement | null>(null);
   const debouncedSearchQuery = useDebounce(searchQuery, 300);
 
+  function handleSortChange(newSort: SortOption) {
+    // Toggle order if clicking same field, else default to desc
+    const newOrder = newSort === sortBy && urlOrder === 'desc' ? 'asc' : 'desc';
+    setSearchParams((prev) => {
+      const next = new URLSearchParams(prev);
+      next.set('sort', newSort);
+      next.set('order', newOrder);
+      return next;
+    }, { replace: true });
+    onSortChange?.(newSort, newOrder);
+  }
+
   useEffect(() => {
     onSearchChange?.(debouncedSearchQuery);
   }, [debouncedSearchQuery, onSearchChange]);
@@ -131,6 +150,7 @@ export function CampaignsTable({
       statusFilter,
       "", // server-side search, no client search
     );
+    // Server already sorted; only apply client-side sort as a tie-break fallback
     return sortCampaigns(filtered, sortBy);
   }, [campaigns, assetCode, statusFilter, sortBy]);
 
@@ -229,7 +249,7 @@ export function CampaignsTable({
           <span>Sort:</span>
           <SortDropdown
             value={sortBy}
-            onChange={setSortBy}
+            onChange={handleSortChange}
             disabled={isLoading}
           />
         </label>

frontend/src/services/api.ts

@@ -27,6 +27,8 @@ export async function listCampaigns(filters?: {
   status?: string;
   page?: number;
   limit?: number;
+  sort?: string;
+  order?: string;
 }): Promise<CampaignListResponse> {
   const params = new URLSearchParams();
   if (filters?.includeDeleted) {
@@ -47,6 +49,12 @@ export async function listCampaigns(filters?: {
   if (filters?.limit !== undefined) {
     params.set('limit', String(filters.limit));
   }
+  if (filters?.sort) {
+    params.set('sort', filters.sort);
+  }
+  if (filters?.order) {
+    params.set('order', filters.order);
+  }
 
   const query = params.toString();
   return apiRequest<CampaignListResponse>({