# Sub-project C — UX Extensions

**Datum:** 2026-05-21
**Status:** Draft, ready for review
**Parent app:** Flashcard webapplicatie
**Voorgaande specs:** `2026-05-20-auth-and-roles-design.md` (A, opgeleverd), `2026-05-20-ownership-and-sharing-design.md` (B, opgeleverd)
**Scope:** Derde en laatste van drie subprojecten in de multi-user uitbreiding (A→B→C).

---

## 1. Doel

De gebruikerservaring van de flashcard-app op een professioneel niveau brengen door vier samenhangende UX-uitbreidingen:

1. **Les-detailpagina** — één rijke pagina die overzicht, statistiek, sublessen en kaarten samenbrengt
2. **App-brede search** — een ⌘K-stijl command-palette die zowel lessen als kaarten doorzoekt
3. **Statistieken-pagina** — heatmap + per-les voortgang + reviews-due overzicht
4. **Admin-lessen polish** — drag-and-drop herordening + inline filter in de lessen-boom

Geen nieuwe data-modellen. Wel drie nieuwe backend endpoints (search, lessons-progress, due-overview).

## 2. Uitgangspunten

- **Routes restructureren**: `/admin` → `/lessons`, `/admin/lessons/:id` → `/lessons/:id`. Oude routes worden client-side `<Navigate replace>` redirects.
- **Geen extra charts-library**: heatmap en progressbars met Tailwind + simpele SVG.
- **Drag-and-drop library**: `@dnd-kit/core` + `@dnd-kit/sortable`.
- **Search-strategie**: SQLite `LIKE %q%` zonder FTS5. Bovengrens: 30 lessen + 30 kaarten per query. Debounce 200ms in UI.
- **Sublessen op detail page**: alleen directe children; diepere navigatie via doorklikken.
- **Card preview op detail page**: client-side limit 30; "Toon alle X" expandt.

## 3. Functionele eisen

### 3.1 Les-detailpagina (`/lessons/:id`)

Vervangt `AdminLessonPage`. Eén pagina, in vier secties + header.

**Header**
- Breadcrumb-pad (parents → huidige les)
- Titel + beschrijving inline-editable voor eigenaar (klik op tekst → input → blur saves)
- Badges: 🔒 Privé / 🌍 Gedeeld / ⭐ Curated / 📥 Geabonneerd
- Primary CTA: **"Start oefenen →"** (groot, gradient)
- Secundaire acties (rechts uitgelijnd):
  - Eigenaar: Visibility-toggle, Curated-toggle (sysadmin op shared lesson), Importeer Excel, Exporteer Excel, Verwijder les
  - Niet-eigenaar geabonneerd: Fork, Abonnement opzeggen
  - Niet-eigenaar niet-geabonneerd (curated): Fork, Abonneer

**Sectie 1: Stats summary** — 4 horizontale stat-cards (compact):
- Kaarten — totaal recursief over subtree
- Beheerst — count(box≥4) / totaal, met percentage
- Score — gewogen gemiddelde van card scores
- Laatst geoefend — relatieve tijd (bv. "3 dagen geleden")

**Sectie 2: Sublessen** (verbergen indien leeg)
- Lijst met: naam, # kaarten (recursief), score%, klikbaar → `/lessons/:childId`
- Voor eigenaar: "+ Subles" knop opent inline form

**Sectie 3: Kaarten**
- Voor eigenaar: bestaande `CardTable` (editable), default 30 zichtbaar, "Toon alle X" knop expandt
- Voor niet-eigenaar: read-only weergave van dezelfde tabel
- Empty state: "Nog geen kaarten — voeg er hieronder een toe" (eigenaar) of "Deze les heeft nog geen kaarten" (niet-eigenaar)

**Sectie 4: Recente sessies op deze les**
- Laatste 5 voltooide sessies voor deze user op deze les
- Per rij: datum, score%, duur

### 3.2 App-brede search

**Backend endpoint**: `GET /api/search?q=<term>&limit=30`
- Authenticatie vereist
- Min query length: 2 chars; lege query → `{ lessons: [], cards: [] }`
- Doorzoekt:
  - **Lessen**: alle waar `canReadLesson(currentUser, lesson)` of (`visibility='shared'` en owner ≠ currentUser) — d.w.z. eigen library + marketplace
  - **Kaarten**: alleen kaarten in lessen die de user mag lezen (geen marketplace cards — die staan niet in de "library")
- Match op `LIKE %q%` (lowercase) op `lessons.name`, `lessons.description`, `cards.question`, `cards.answer`, `cards.hint`
- Response:
  ```ts
  {
    lessons: Array<{
      id: number;
      name: string;
      ownerDisplayName: string;
      location: 'library' | 'marketplace';
      totalCards: number;
      isCurated: boolean;
    }>;
    cards: Array<{
      id: number;
      lessonId: number;
      lessonName: string;
      question: string;
      snippet: string; // first 80 chars of question or answer with match
    }>;
  }
  ```
- Sort: lessen `library` eerst, dan `marketplace`; binnen elke groep alfabetisch
- Kaarten: alfabetisch op lesson name + question

**Frontend**
- **Trigger**: ⌘K / Ctrl+K (global key listener) of klik op zoekicoon in header
- **Modal**: full-screen overlay met centered command-palette panel
- **Input**: autofocus, debounced 200ms request
- **Sections**: "Lessen — Jouw bibliotheek", "Lessen — Marketplace", "Kaarten"
- **Keyboard nav**: ↑/↓ door results, Enter selecteert, Esc sluit
- **Click/Enter**:
  - Lesson result → `/lessons/:id`
  - Card result → `/lessons/:lessonId#card-:id` (anchor scrollt + flash highlight)
- **Empty/error states**: "Begin met typen om te zoeken", "Geen resultaten gevonden", error message

### 3.3 Statistieken-pagina (`/stats`)

Vervangt huidige `StatsPage`. Drie blokken in deze volgorde.

#### A. Activiteit-heatmap (12 maanden)
- Bron: `GET /api/stats/heatmap?weeks=52`
- Component: `Heatmap`
- Layout: 53 kolommen × 7 rijen (per dag een cell). Kleur intensiteit op basis van `attempts`:
  - 0 → gray-100
  - 1–4 → success-200
  - 5–14 → success-400
  - 15–49 → success-500
  - 50+ → success-700
- Maand-labels boven, weekday-labels links (Ma, Wo, Vr)
- Tooltip op hover: "X mei: Y pogingen, Z sessies"

#### B. Voortgang per les
- Backend: `GET /api/stats/lessons-progress`
  ```ts
  {
    rows: Array<{
      lessonId: number;
      name: string;
      totalCards: number;
      masteredCards: number; // box >= 4
      scorePct: number;       // 0..100, computed like getLessonStats
      lastSessionAt: number | null;
    }>;
  }
  ```
  Alleen **root-lessen** van de user's tree (lessen waar canRead + parent ofwel null of niet zichtbaar). Sublessen aggregeren in de root.
- Frontend: gesorteerde lijst (default: hoogste score eerst; sortable op naam/score/laatst).
  Per rij:
  - Lesnaam (link → `/lessons/:id`)
  - Progressbar: mastered/total fractie, achtergrond brand-100, vulling success-500
  - Score% rechts
  - Laatst geoefend relative time

#### C. Reviews-due overzicht
- Backend: `GET /api/stats/due`
  ```ts
  {
    overdue: number;     // next_due_at < now()
    today: number;       // due tussen now en eindigend at midnight UTC
    tomorrow: number;    // morgen
    thisWeek: number;    // 7 dagen incl. vandaag
  }
  ```
  Berekend over alle `card_progress` rijen van de user op cards in lessen die hij kan lezen.
- Frontend: 4 grote "badges" met aantallen en kleuren (overdue=red, today=brand, tomorrow=success, thisWeek=slate)
- CTA-knop onder: **"Start review (X kaarten)"** start een sessie op een speciale "due-only" mode. Voor v1 implementatie: navigate naar `/practice/__due__/setup` met een query `?mode=due` die de session start filtert op enkel due cards over de hele library.
  - Dit vereist een uitbreiding: `POST /api/sessions` accepteert `{ lessonId: 'due', mode: 'due' }` of een nieuwe alias-route `POST /api/sessions/due` die een sessie maakt over **alle** due cards van de user.
  - **Eenvoudiger compromis**: een nieuw endpoint `POST /api/sessions/due` dat dit verzorgt. Spec kiest deze variant.

### 3.4 Admin polish — `/lessons` (lessen-tree)

**Inline filter**
- Tekstveld bovenin de tree (zelfde rij als "Nieuwe wortel-les...")
- Live filter (geen debounce nodig, alles client-side)
- Case-insensitive substring match op `name`
- Bij hit: het node + alle voorouders blijven zichtbaar
- Bij geen-hit: voorouders gedimd, geen-hit-nodes verborgen
- Bij geen filter: alles normaal

**Drag-and-drop**
- Library: `@dnd-kit/core` + `@dnd-kit/sortable`
- Alleen lessen die de user bezit zijn sleepbaar (`isOwner`)
- Drop targets: een andere positie binnen dezelfde parent (herordenen) of in een andere les (re-parent)
- Bij drop: client roept `POST /api/lessons/:id/move` aan met nieuwe `parentId` en `position`
- Visual feedback: drop-zone hint highlight, snap-back op invalid drop
- Keyboard support: dnd-kit's built-in (pijltoetsen + space om op te pakken)
- Restrictions enforced client-side: niet eigenaar → geen drag handle; restricties op backend (cycle check) blijven gelden

## 4. Datamodel

**Geen wijzigingen**.

## 5. API-overzicht

### Nieuw

```
GET  /api/search?q=<term>&limit=30           # globale zoek
GET  /api/stats/lessons-progress             # voortgang per root-les
GET  /api/stats/due                          # due counts
POST /api/sessions/due                       # speciale sessie over alle due cards
```

### Aangepast

```
GET /api/stats/heatmap                       # default weeks 12 → 52
```

## 6. Routes-restructure (frontend)

| Oud | Nieuw | Migratie |
|---|---|---|
| `/admin` | `/lessons` | `<Navigate to="/lessons" replace />` |
| `/admin/lessons/:id` | `/lessons/:id` | `<Navigate to="/lessons/${id}" replace />` |
| `/admin/users` | `/admin/users` | (ongewijzigd; alleen sysadmin) |

Nav-link "Lessen" in `Layout` wijst naar `/lessons`.

## 7. UI-componenten

### Nieuwe

| Bestand | Verantwoordelijkheid |
|---|---|
| `pages/LessonDetail.tsx` | Detail page met header + stats + sublessen + kaarten + recente sessies |
| `pages/Lessons.tsx` | Vervangt `Admin.tsx`; tree-pagina met filter + drag-drop |
| `components/SearchPalette.tsx` | Cmd-K modal met grouped results |
| `components/LessonStatsPanel.tsx` | 4 mini stat-cards voor detail page header |
| `components/SublessonList.tsx` | Lijst sublessen met progress |
| `components/RecentSessionsList.tsx` | Laatste 5 sessies op les |
| `components/Heatmap.tsx` | 12-maands grid |
| `components/LessonProgressList.tsx` | Sortable lijst met progressbars |
| `components/DueOverviewCard.tsx` | 4-badge widget met "Start review" CTA |
| `api/search.ts` | Client voor `/api/search` |

### Aanpassingen

| Bestand | Wat |
|---|---|
| `components/Layout.tsx` | + Search icoon + Cmd-K listener; "Lessen" link → `/lessons` |
| `components/LessonTree.tsx` | + filter prop, + drag-drop (dnd-kit) |
| `pages/Stats.tsx` | Volledig herschrijven naar drie nieuwe componenten |
| `router.tsx` | Routes restructuren + redirects |
| `services/sessions.ts` | + `startDueSession(userId)` |
| `routes/sessions.ts` | + `POST /due` |
| `services/stats.ts` | + `getLessonsProgress(userId)`, `getDueOverview(userId)` |
| `routes/stats.ts` | + `/lessons-progress`, `/due` |
| `services/search.ts` | Nieuw service module |
| `routes/search.ts` | Nieuwe router |
| `app.ts` | Mount nieuwe routers |

### Te verwijderen

- `pages/AdminLesson.tsx` → vervangen door `pages/LessonDetail.tsx`
- `pages/Admin.tsx` → vervangen door `pages/Lessons.tsx`

## 8. Tests

### Backend unit

- `search.test.ts`: filter op canRead, marketplace inclusion, card snippet generation, empty query, special chars
- `stats.test.ts` (extend): `getLessonsProgress` per-root grouping, `getDueOverview` bucket boundaries

### Backend integration

- `/api/search`: user A's private niet in user B's results; curated zichtbaar voor B; marketplace lessons; cards niet uit marketplace
- `/api/stats/lessons-progress`: alleen roots; correct aggregeren over subtree
- `/api/stats/due`: edge cases (geen kaarten, alles future, alles overdue)
- `/api/sessions/due`: start sessie met alleen due cards

### Frontend unit (Vitest + RTL)

- `SearchPalette`: opent op ⌘K, debouncing, keyboard navigation, click navigation
- `LessonStatsPanel`: rendering met null/zero waarden
- `Heatmap`: kleurintensiteit-buckets, tooltip
- `LessonTree`: filter-functie, drag-drop call op move

### E2E (Playwright)

- Detail-page flow: open lesson, zie sublessen, start practice
- Search flow: ⌘K, type query, klik result → navigatie naar detail
- Stats page laadt en toont alle drie blokken
- Drag-drop reorder (smoke; kan flaky zijn — accept een minimum-versie)

## 9. Performance / a11y

- Search backend: response time-budget 200ms voor q<=10 cards/lessons (typische tree). Met `LIKE %q%` zonder index is dit OK voor verwachte schaal (~1000 lessen, ~10000 kaarten). Indien problematisch later: FTS5 index.
- Heatmap rendert als statisch SVG/grid (max 371 cells × kleine div). Geen virtualization nodig.
- Cmd-K modal: focus management (autofocus input, Tab cycle binnen modal, Esc sluit, return focus naar trigger)
- Drag-drop: `prefers-reduced-motion` respect via dnd-kit's `MeasuringStrategy.Always` + animated reorder kan uit
- All interactive elements ARIA-labeled

## 10. Migratie

Geen DB-wijzigingen. Frontend route-redirects voor bookmarks naar oude URLs.

## 11. Out of scope (YAGNI)

- Card-level detail-pagina re-design (`/stats/cards/:id` blijft staan)
- Bulk-operaties op kaarten (multi-select, batch delete/move)
- Duplicate-lesson knop (fork dekt het)
- Charts-library (recharts, echarts) — voor 3 blokken niet nodig
- Search saved queries / search history
- Box-distributie chart, cumulative study curve, streak milestones (afgewezen tijdens brainstorm)
- FTS5 full-text search index
- Pagineren in search results boven de 30
- Editing van een card via search-modal (alleen navigatie)
- Bulk move bij drag-drop (één les per keer)
- Drag-drop reorder van cards binnen een les