Merge feature/wow-dashboard: hero + insights dashboard redesign

Author: mayur-tolexo

docs/superpowers/specs/2026-05-25-wow-dashboard-design.md

@@ -0,0 +1,97 @@
+# "Wow" dashboard redesign — Design
+
+Date: 2026-05-25
+Status: Approved for implementation
+
+Redesign the logged-in dashboard (`/dashboard`) around three pillars: a hero with your profile link + live preview, beautiful insights, and premium polish. Two tracks (Go backend, web frontend), disjoint files → parallelizable.
+
+## Contract (normative)
+New authed endpoint: `GET /api/v1/insights` → `{ "daily": DailyStat[] }`
+- `DailyStat = { "date": "YYYY-MM-DD", "views": number, "clicks": number }`
+- Exactly 14 entries, ascending by date, ending today (`today-13 … today`), **zero-filled** for days with no activity. Scope: all carts owned by the viewer.
+
+Everything else the dashboard needs (per-cart `viewsLast7d/clicksLast7d/reachLast7d`, totals, top cart) is already in `listMyCarts()` — computed on the frontend. The daily series is the only new data.
+
+---
+
+## Workstream A — Backend (Go)
+
+### sqlc queries (append to `internal/db/queries.sql`, regen with `"$(go env GOPATH)/bin/sqlc" generate`)
+```sql
+-- name: AccountDailyViews :many
+SELECT cv.day::date AS day, COALESCE(SUM(cv.views), 0)::bigint AS views
+FROM cart_views_daily cv
+JOIN carts c ON c.id = cv.cart_id
+WHERE c.user_id = $1 AND cv.day >= current_date - 13
+GROUP BY cv.day
+ORDER BY cv.day;
+
+-- name: AccountDailyClicks :many
+SELECT cd.day::date AS day, COALESCE(SUM(cd.clicks), 0)::bigint AS clicks
+FROM click_daily cd
+JOIN links l ON l.id = cd.link_id
+JOIN carts c ON c.id = l.cart_id
+WHERE c.user_id = $1 AND cd.day >= current_date - 13
+GROUP BY cd.day
+ORDER BY cd.day;
+```
+(`links.cart_id` is nullable; the JOIN naturally drops non-cart links.)
+
+### Service (`internal/carts/service.go`)
+- `AccountDailyStats(ctx, userID int64) ([]DailyStat, error)`: run both queries, merge by date into a **14-day, ascending, zero-filled** slice covering `today-13 … today` (build the date skeleton in Go using `time.Now().UTC()`, then fill from the query rows keyed by date). `DailyStat` is a small struct `{ Date time.Time / string, Views int64, Clicks int64 }`.
+
+### Marshal (`internal/carts/marshal.go`)
+- `DailyStatJSON { Date string `json:"date"`; Views int `json:"views"`; Clicks int `json:"clicks"` }` with `Date` formatted `"2006-01-02"`. A `MarshalDailyStats([]DailyStat) []DailyStatJSON` helper.
+
+### Handler (`internal/carts/handlers.go`)
+- Add `r.Get("/insights", getInsights(svc))` inside `RegisterRoutes` (already under `/api/v1` + `RequireUser`).
+- `getInsights`: read `uid` from context, call `AccountDailyStats`, write `{"daily": MarshalDailyStats(...)}` (200). On error → 500.
+
+### Tests
+- `internal/carts/service_test.go` or `handlers_test.go`: seed `cart_views_daily` + `click_daily` across several days (incl. a gap day) for the user's cart(s); assert the series is length 14, ascending, zero-filled on the gap, correct sums, and excludes another user's carts. Handler test: `GET /api/v1/insights` returns a 14-element `daily` array.
+
+### Files (A) — no web/
+`internal/db/queries.sql`, `internal/db/sqlc/*` (regen), `internal/carts/service.go`, `internal/carts/marshal.go`, `internal/carts/handlers.go`, `internal/carts/{service,handlers}_test.go`.
+
+---
+
+## Workstream B — Frontend (web)
+
+### Types + client
+- `web/lib/types.ts`: `export interface DailyStat { date: string; views: number; clicks: number }`.
+- `web/lib/api-client.ts`: `getInsights(opts?: AuthOpts): Promise<DailyStat[]>` → `GET /api/v1/insights`, returns the `daily` array (`[]` on absence).
+- `web/lib/insights.ts` (pure, tested): `summarizeDaily(daily: DailyStat[])` → `{ viewsThisWeek, viewsPrevWeek, viewsDeltaPct, clicksThisWeek, clicksPrevWeek, clicksDeltaPct }` (last 7 vs the prior 7; delta `null`/0-safe when prev week is 0). Unit-tested (node-env vitest).
+
+### Components
+- `web/components/sparkline.tsx` — pure inline **SVG** sparkline from `values: number[]` (props: values, width, height, className for stroke). No chart library. Renders nothing/flat baseline for all-zero input.
+- `web/components/dashboard-hero.tsx` (`"use client"`) — props `{ user }`. Left: greeting (avatar + "Hi {firstName}" + warm line) and the **profile link** ``{origin}/u/{handle}`` with **Copy** (reuse `lib/clipboard.ts`) + **Share** (reuse `share-sheet.tsx` or `navigator.share`). Right (lg+): a **live preview** — reuse `web/components/phone-frame.tsx` wrapping an `<iframe src={`/u/${handle}`} loading="lazy">` scaled to fit. Below `lg`: hide the phone, show a "View my profile →" link to `/u/{handle}`. Warm accent gradient background. Guard: if `handle` is empty, show the greeting without the link/preview.
+- `web/components/insight-summary.tsx` — headline **views this week** via `AnimatedNumber`, a ▲/▼ **delta** chip vs last week (green up / muted down, from `summarizeDaily`), the `Sparkline` (14-day views), and a compact chip row: clicks (7d), reach (7d, summed from carts), carts count, products count. Server or client component (no interactivity needed beyond AnimatedNumber).
+- `web/components/top-cart-card.tsx` — featured "⭐ Top cart" = the cart with the highest `viewsLast7d` (passed in). Larger cover, title, its views/clicks. Links to `/dashboard/carts/{id}`. Hidden if no carts have any views.
+
+### Page (`web/app/dashboard/page.tsx`)
+- Fetch `user`, `carts`, and `getInsights()` in parallel (forward cookie; insights failure → `[]`, never break the page).
+- Layout (has carts): `<DashboardHero user={user} />` → `<InsightSummary daily={...} carts={...} />` + `<TopCartCard .../>` → header row ("Your carts" + Add/New cart) → cart grid (reuse `CartCard`, wrap in `RevealOnScroll` for entrance). Keep `InstallNudge`.
+- Empty state: keep `FirstTimeOnboarding` (a slimmed hero greeting is fine; skip insights/top-cart when there are no carts).
+- Premium polish: warm gradient in hero, `RevealOnScroll` entrance on grid, existing hover-lift on cards, refined serif hierarchy. Keep within the existing theme tokens (ink/cream/paper/accent/muted/rule).
+
+### Mobile
+Hero stacks (phone preview hidden → "View my profile" link); insight chips wrap; sparkline is responsive width; grid stays `grid-cols-1 sm:grid-cols-2 lg:grid-cols-3`; ≥44px tap targets; keep `pb-24 sm:pb-10`.
+
+### Tests
+- `web/lib/insights.test.ts` (summarizeDaily: week split, delta %, zero-prev-week safety, short arrays).
+- `web/lib/api-client.test.ts`: `getInsights` builds `/api/v1/insights` (GET).
+(Sparkline/hero are visual; not unit-tested — keep logic in the tested pure helper.)
+
+### Files (B) — no Go
+Create: `web/lib/insights.ts`, `web/lib/insights.test.ts`, `web/components/sparkline.tsx`, `web/components/dashboard-hero.tsx`, `web/components/insight-summary.tsx`, `web/components/top-cart-card.tsx`.
+Modify: `web/lib/types.ts`, `web/lib/api-client.ts`, `web/app/dashboard/page.tsx`.
+Reuse: `phone-frame.tsx`, `lib/clipboard.ts`, `share-sheet.tsx`, `animated-number.tsx`, `cart-card.tsx`, `reveal-on-scroll.tsx`, `install-nudge.tsx`.
+
+---
+
+## Verification
+- Backend: `go build ./...`, `go vet ./...`, `go test ./internal/carts/... -race -count=1`; golangci-lint if present.
+- Frontend: `pnpm exec tsc --noEmit`, `pnpm lint`, `pnpm test`. (Integrator runs the authoritative `pnpm build` + a logged-in visual check.)
+
+## Out of scope
+Per-cart trend charts; configurable date ranges (fixed 14-day); earnings/revenue; real-time updates.

internal/carts/handlers.go

@@ -15,6 +15,7 @@ import (
 // RegisterRoutes mounts /carts/*, /me, /og-fetch under the parent router.
 func RegisterRoutes(r chi.Router, svc *Service, fetcher *ogfetch.Fetcher) {
 	r.Get("/me", getMe(svc))
+	r.Get("/insights", getInsights(svc))
 	r.Get("/cover-images", listCoverImages(svc))
 	r.Get("/carts", listCarts(svc))
 	r.Post("/carts", createCart(svc))
@@ -40,6 +41,18 @@ func getMe(svc *Service) http.HandlerFunc {
 	}
 }
 
+func getInsights(svc *Service) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		uid, _ := auth.UserIDFromContext(r.Context())
+		stats, err := svc.AccountDailyStats(r.Context(), uid)
+		if err != nil {
+			http.Error(w, err.Error(), http.StatusInternalServerError)
+			return
+		}
+		writeJSON(w, http.StatusOK, map[string][]DailyStatJSON{"daily": MarshalDailyStats(stats)})
+	}
+}
+
 func listCoverImages(svc *Service) http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
 		uid, _ := auth.UserIDFromContext(r.Context())

internal/carts/handlers_test.go

@@ -102,6 +102,30 @@ func TestGETMe_ReturnsUser(t *testing.T) {
 	assert.Equal(t, "Test User", u["displayName"])
 }
 
+func TestGETInsights_Returns14DayDaily(t *testing.T) {
+	r, _ := setupHandlers(t)
+	req := httptest.NewRequest(http.MethodGet, "/api/v1/insights", nil)
+	rr := httptest.NewRecorder()
+	r.ServeHTTP(rr, req)
+	assert.Equal(t, http.StatusOK, rr.Code)
+
+	var out struct {
+		Daily []struct {
+			Date   string `json:"date"`
+			Views  int    `json:"views"`
+			Clicks int    `json:"clicks"`
+		} `json:"daily"`
+	}
+	require.NoError(t, json.Unmarshal(rr.Body.Bytes(), &out))
+	require.Len(t, out.Daily, 14)
+	// Ascending by date, zero-filled (no activity seeded).
+	for i := 1; i < len(out.Daily); i++ {
+		assert.Less(t, out.Daily[i-1].Date, out.Daily[i].Date)
+	}
+	assert.Equal(t, 0, out.Daily[0].Views)
+	assert.Equal(t, 0, out.Daily[0].Clicks)
+}
+
 func TestPOSTCartItems_AddsExplicitProduct(t *testing.T) {
 	r, _ := setupHandlers(t)
 	// create cart

internal/carts/marshal.go

@@ -97,6 +97,27 @@ func MarshalCart(c sqlcgen.Cart, owner sqlcgen.User, items []sqlcgen.ListCartIte
 	return out
 }
 
+// DailyStatJSON is the frontend-compatible JSON shape for a single day's stats.
+type DailyStatJSON struct {
+	Date   string `json:"date"`
+	Views  int    `json:"views"`
+	Clicks int    `json:"clicks"`
+}
+
+// MarshalDailyStats converts a DailyStat series into JSON shapes, formatting the
+// date as "YYYY-MM-DD". Always returns a non-nil slice so it serializes as [].
+func MarshalDailyStats(stats []DailyStat) []DailyStatJSON {
+	out := make([]DailyStatJSON, 0, len(stats))
+	for _, s := range stats {
+		out = append(out, DailyStatJSON{
+			Date:   s.Date.Format("2006-01-02"),
+			Views:  int(s.Views),
+			Clicks: int(s.Clicks),
+		})
+	}
+	return out
+}
+
 func intStr(i int64) string {
 	return strconv.FormatInt(i, 10)
 }

internal/carts/service.go

@@ -3,6 +3,7 @@ package carts
 import (
 	"context"
 	"errors"
+	"time"
 
 	"github.com/jackc/pgx/v5"
 	"github.com/jackc/pgx/v5/pgtype"
@@ -70,6 +71,66 @@ func (s *Service) CartStats7d(ctx context.Context, cartID int64) (views, clicks,
 	return views, clicks, reach
 }
 
+// DailyStat is a single day's view and click totals across all of a user's carts.
+type DailyStat struct {
+	Date   time.Time
+	Views  int64
+	Clicks int64
+}
+
+// dailySeriesDays is the fixed window length of the insights series.
+const dailySeriesDays = 14
+
+// dateKey is the canonical day key used to merge query rows onto the skeleton.
+const dateKey = "2006-01-02"
+
+// AccountDailyStats returns a 14-day, ascending, zero-filled series of view and
+// click totals across all carts owned by userID, covering today-13 … today.
+//
+// The date skeleton is built in Go from time.Now().UTC() so every day is present
+// even when the underlying tables have no rows for it; the SQL queries only
+// return days with activity and we merge those onto the skeleton by date.
+func (s *Service) AccountDailyStats(ctx context.Context, userID int64) ([]DailyStat, error) {
+	viewRows, err := s.q.AccountDailyViews(ctx, userID)
+	if err != nil {
+		return nil, err
+	}
+	clickRows, err := s.q.AccountDailyClicks(ctx, userID)
+	if err != nil {
+		return nil, err
+	}
+
+	views := make(map[string]int64, len(viewRows))
+	for _, r := range viewRows {
+		if r.Day.Valid {
+			views[r.Day.Time.UTC().Format(dateKey)] = r.Views
+		}
+	}
+	clicks := make(map[string]int64, len(clickRows))
+	for _, r := range clickRows {
+		if r.Day.Valid {
+			clicks[r.Day.Time.UTC().Format(dateKey)] = r.Clicks
+		}
+	}
+
+	// Anchor "today" in UTC to match how DATE columns are stored/compared
+	// (current_date in the queries). Truncate to the day boundary.
+	now := time.Now().UTC()
+	today := time.Date(now.Year(), now.Month(), now.Day(), 0, 0, 0, 0, time.UTC)
+
+	out := make([]DailyStat, 0, dailySeriesDays)
+	for i := dailySeriesDays - 1; i >= 0; i-- {
+		day := today.AddDate(0, 0, -i)
+		key := day.Format(dateKey)
+		out = append(out, DailyStat{
+			Date:   day,
+			Views:  views[key],
+			Clicks: clicks[key],
+		})
+	}
+	return out, nil
+}
+
 // ListMyCoverImages returns the distinct cover image URLs the user has used
 // across their carts, most-recent first — their "personal" cover library.
 func (s *Service) ListMyCoverImages(ctx context.Context, userID int64) ([]string, error) {

internal/carts/service_test.go

@@ -3,7 +3,9 @@ package carts_test
 import (
 	"context"
 	"testing"
+	"time"
 
+	"github.com/jackc/pgx/v5/pgxpool"
 	"github.com/mayur-tolexo/shoplit/internal/auth"
 	"github.com/mayur-tolexo/shoplit/internal/carts"
 	"github.com/mayur-tolexo/shoplit/internal/db"
@@ -14,6 +16,14 @@ import (
 )
 
 func setupSvc(t *testing.T) (*carts.Service, int64) {
+	svc, uid, _, _ := setupSvcWithPool(t)
+	return svc, uid
+}
+
+// setupSvcWithPool is like setupSvc but also exposes the raw pool and Queries so
+// tests can seed analytics tables (cart_views_daily / click_daily) on arbitrary
+// days — the Bump* queries only ever write current_date.
+func setupSvcWithPool(t *testing.T) (*carts.Service, int64, *pgxpool.Pool, *sqlcgen.Queries) {
 	pool, dsn := testutil.NewPostgres(t)
 	require.NoError(t, db.MigrateUp(dsn, "../db/migrations"))
 	q := sqlcgen.New(pool)
@@ -23,7 +33,7 @@ func setupSvc(t *testing.T) (*carts.Service, int64) {
 		Sub: "g-1", Email: "test@example.com", Name: "Test User", Picture: "https://example.com/a.jpg",
 	})
 	require.NoError(t, err)
-	return carts.NewService(q), uid
+	return carts.NewService(q), uid, pool, q
 }
 
 func TestService_CreateAndListCart(t *testing.T) {
@@ -155,3 +165,96 @@ func TestService_GetPublicCart_PublicVisibleToAnon(t *testing.T) {
 	require.NoError(t, err)
 	assert.Equal(t, cart.ID, got.ID)
 }
+
+func TestService_AccountDailyStats(t *testing.T) {
+	svc, uid, pool, _ := setupSvcWithPool(t)
+	ctx := context.Background()
+
+	// The viewer's cart, with a link to attribute clicks to.
+	cart, err := svc.CreateCart(ctx, uid, "Mine")
+	require.NoError(t, err)
+	item, err := svc.AddProduct(ctx, uid, cart.ID, carts.AddProductInput{
+		OriginalURL: "https://example.com/x", Retailer: "other", Title: "P1",
+	})
+	require.NoError(t, err)
+	// The link backing the item is what click_daily references.
+	var linkID int64
+	require.NoError(t, pool.QueryRow(ctx,
+		`SELECT link_id FROM cart_items WHERE id = $1`, item.ID).Scan(&linkID))
+
+	// Another user with their own cart + analytics — must NOT leak into uid's series.
+	q := sqlcgen.New(pool)
+	other, err := auth.NewUserUpsertFn(q)(auth.GoogleUserInfo{
+		Sub: "g-other", Email: "other@example.com", Name: "Other", Picture: "",
+	})
+	require.NoError(t, err)
+	otherSvc := carts.NewService(q)
+	otherCart, err := otherSvc.CreateCart(ctx, other, "Theirs")
+	require.NoError(t, err)
+	otherItem, err := otherSvc.AddProduct(ctx, other, otherCart.ID, carts.AddProductInput{
+		OriginalURL: "https://example.com/y", Retailer: "other", Title: "P2",
+	})
+	require.NoError(t, err)
+	var otherLinkID int64
+	require.NoError(t, pool.QueryRow(ctx,
+		`SELECT link_id FROM cart_items WHERE id = $1`, otherItem.ID).Scan(&otherLinkID))
+
+	// Seed views on day offsets 0, 3, 13 (gap on day 1, 2, etc.) for the viewer.
+	// Offsets are relative to current_date (UTC date in Postgres).
+	seedViews := func(cartID int64, offset, n int32) {
+		_, e := pool.Exec(ctx,
+			`INSERT INTO cart_views_daily (cart_id, day, views) VALUES ($1, current_date - ($2)::int, $3)`,
+			cartID, offset, n)
+		require.NoError(t, e)
+	}
+	seedClicks := func(linkID int64, offset, n int32) {
+		_, e := pool.Exec(ctx,
+			`INSERT INTO click_daily (link_id, day, clicks) VALUES ($1, current_date - ($2)::int, $3)`,
+			linkID, offset, n)
+		require.NoError(t, e)
+	}
+
+	seedViews(cart.ID, 13, 5) // oldest day in window
+	seedViews(cart.ID, 3, 7)
+	seedViews(cart.ID, 0, 11) // today
+	seedClicks(linkID, 3, 2)
+	seedClicks(linkID, 0, 4)
+
+	// Out-of-window view (14 days ago) must be excluded.
+	seedViews(cart.ID, 14, 99)
+	// Another user's activity on day 0 must be excluded.
+	seedViews(otherCart.ID, 0, 1000)
+	seedClicks(otherLinkID, 0, 1000)
+
+	stats, err := svc.AccountDailyStats(ctx, uid)
+	require.NoError(t, err)
+
+	// Exactly 14 entries, ascending by date, ending today.
+	require.Len(t, stats, 14)
+	today := time.Now().UTC().Truncate(24 * time.Hour)
+	for i, s := range stats {
+		want := today.AddDate(0, 0, -(13 - i))
+		assert.Equal(t, want.Format("2006-01-02"), s.Date.Format("2006-01-02"),
+			"entry %d should be ascending", i)
+	}
+
+	// Zero-filled on the gap days; correct sums on the seeded days.
+	// index 0 == today-13, index 10 == today-3, index 13 == today.
+	assert.EqualValues(t, 5, stats[0].Views)
+	assert.EqualValues(t, 0, stats[0].Clicks)
+	assert.EqualValues(t, 0, stats[1].Views, "gap day must be zero-filled")
+	assert.EqualValues(t, 0, stats[1].Clicks)
+	assert.EqualValues(t, 7, stats[10].Views)
+	assert.EqualValues(t, 2, stats[10].Clicks)
+	assert.EqualValues(t, 11, stats[13].Views)
+	assert.EqualValues(t, 4, stats[13].Clicks)
+
+	// Totals reflect only the viewer's carts (other user's 1000s excluded).
+	var totalViews, totalClicks int64
+	for _, s := range stats {
+		totalViews += s.Views
+		totalClicks += s.Clicks
+	}
+	assert.EqualValues(t, 5+7+11, totalViews)
+	assert.EqualValues(t, 2+4, totalClicks)
+}