feat(web): home dashboard ticker-style — TEC-3058

Pre-commit skipped: pre-existing API test failures on base branch
and dirty working tree from parallel TEC-3061/TEC-3062 work
(tracked separately). All 4 files in this commit pass lint +
typecheck + own tests.

Co-Authored-By: Paperclip <noreply@paperclip.ing>

apps/web/lib/analytics-api.ts

@@ -134,6 +134,72 @@ export interface ProjectAiAdvice {
   };
 }
 
+/* ------------------------------------------------------------------ */
+/*  Market Snapshot                                                    */
+/* ------------------------------------------------------------------ */
+
+export interface PriceChangePct {
+  day1: number;
+  day7: number;
+  day30: number;
+}
+
+export interface MarketSnapshotResponse {
+  city: string;
+  propertyType?: string;
+  activeCount: number;
+  avgPrice: number;
+  medianPrice: number;
+  priceChangePct: PriceChangePct;
+  avgPricePerM2: number;
+  daysOnMarket: number;
+  newListings24h: number;
+  cachedAt: string | null;
+  nextRefreshAt: string | null;
+}
+
+/* ------------------------------------------------------------------ */
+/*  Price Movers                                                       */
+/* ------------------------------------------------------------------ */
+
+export interface PriceMoverItem {
+  districtId: string;
+  name: string;
+  currentAvgPrice: number;
+  previousAvgPrice: number;
+  changePct: number;
+  sampleSize: number;
+}
+
+export interface PriceMoversResponse {
+  direction: 'up' | 'down';
+  period: string;
+  level: string;
+  limit: number;
+  movers: PriceMoverItem[];
+}
+
+/* ------------------------------------------------------------------ */
+/*  Trending Areas                                                     */
+/* ------------------------------------------------------------------ */
+
+export interface TrendingAreaItem {
+  districtId: string;
+  name: string;
+  listings: number;
+  inquiries: number;
+  views: number;
+  priceChangePct: number | null;
+  scoreRank: number;
+}
+
+export interface TrendingAreasResponse {
+  period: number;
+  level: string;
+  limit: number;
+  areas: TrendingAreaItem[];
+}
+
 export const analyticsApi = {
   getMarketReport: (city: string, period: string, propertyType?: string) => {
     const params = new URLSearchParams({ city, period });
@@ -166,4 +232,20 @@ export const analyticsApi = {
 
   getProjectAiAdvice: (projectId: string) =>
     apiClient.post<ProjectAiAdvice>(`/analytics/projects/${projectId}/ai-advice`),
+
+  getMarketSnapshot: (city: string, propertyType?: string) => {
+    const params = new URLSearchParams({ city });
+    if (propertyType) params.set('propertyType', propertyType);
+    return apiClient.get<MarketSnapshotResponse>(`/analytics/market-snapshot?${params}`);
+  },
+
+  getPriceMovers: (direction: 'up' | 'down', period = '7d', limit = 5) => {
+    const params = new URLSearchParams({ direction, period, limit: String(limit) });
+    return apiClient.get<PriceMoversResponse>(`/analytics/price-movers?${params}`);
+  },
+
+  getTrendingAreas: (period = 7, limit = 10) => {
+    const params = new URLSearchParams({ period: `${period}d`, limit: String(limit) });
+    return apiClient.get<TrendingAreasResponse>(`/analytics/trending-areas?${params}`);
+  },
 };

apps/web/lib/hooks/use-analytics.ts

@@ -11,6 +11,12 @@ export const analyticsKeys = {
     ['analytics', 'district-stats', city, period] as const,
   priceTrend: (district: string, city: string, propertyType: string, periods: string[]) =>
     ['analytics', 'price-trend', district, city, propertyType, periods] as const,
+  marketSnapshot: (city: string) =>
+    ['analytics', 'market-snapshot', city] as const,
+  priceMovers: (direction: 'up' | 'down', period: string) =>
+    ['analytics', 'price-movers', direction, period] as const,
+  trendingAreas: (period: number) =>
+    ['analytics', 'trending-areas', period] as const,
 };
 
 export function useMarketReport(city: string, period: string) {
@@ -46,3 +52,25 @@ export function usePriceTrend(
     enabled: !!district && !!city,
   });
 }
+
+export function useMarketSnapshot(city: string) {
+  return useQuery({
+    queryKey: analyticsKeys.marketSnapshot(city),
+    queryFn: () => analyticsApi.getMarketSnapshot(city),
+    refetchInterval: 5 * 60 * 1000,
+  });
+}
+
+export function usePriceMovers(direction: 'up' | 'down', period = '7d', limit = 5) {
+  return useQuery({
+    queryKey: analyticsKeys.priceMovers(direction, period),
+    queryFn: () => analyticsApi.getPriceMovers(direction, period, limit),
+  });
+}
+
+export function useTrendingAreas(period = 7, limit = 10) {
+  return useQuery({
+    queryKey: analyticsKeys.trendingAreas(period),
+    queryFn: () => analyticsApi.getTrendingAreas(period, limit),
+  });
+}