feat: upgrade education resource browser

Author: kadioko

docs/E2E_TESTING.md

@@ -29,6 +29,7 @@ For protected Vercel previews, configure the automation environment with `VERCEL
 ## Current Coverage
 
 - Public education list and education detail page.
+- Education browser rendering after the automatic search/filter upgrade.
 - Admin credential login.
 - `/api/health`.
 - Dashboard patient and appointment creation entry points.
@@ -56,3 +57,4 @@ These match the seeded staff accounts. Override them for shared environments.
 4. Upload a small test attachment and verify preview/download links.
 5. Submit one clinical form per workflow with generated data.
 6. Add protected-preview GitHub Actions smoke checks once deployment URL discovery is wired in.
+7. Add automatic education search, category filter, sort, and featured-resource checks.

docs/EDUCATION_SYSTEM.md

@@ -0,0 +1,102 @@
+# Education System
+
+Last updated: 2026-05-07
+
+The education area is the public learning library for patients, families, and care teams.
+
+## Public Experience
+
+Public route:
+
+```text
+/education
+```
+
+Resource detail route:
+
+```text
+/education/[id-or-slug]
+```
+
+The public education browser includes:
+
+- Automatic search as the user types.
+- URL-backed filters for category, difficulty, content type, sort order, and page.
+- Featured resource recommendations.
+- Published resource, category, and current result counts.
+- Category buttons with live published-resource counts.
+- Mobile-friendly filter and result layout.
+- Error and empty states that keep the page usable when the content API is unavailable.
+
+## Automatic Behavior
+
+Search is debounced, then written to the URL automatically. That means users can share filtered education links and use browser back/forward naturally.
+
+The content API supports these sorting modes:
+
+- `newest`
+- `popular`
+- `title-asc`
+- `title-desc`
+
+Featured resources are loaded automatically from published content marked `isFeatured`.
+
+## Content Management
+
+Dashboard route:
+
+```text
+/dashboard/education
+```
+
+Admins and healthcare providers can:
+
+- Add a new education resource.
+- Review draft and published resources.
+- Publish or unpublish resources.
+- Open resources from the dashboard list.
+
+Content creation route:
+
+```text
+/education/new
+```
+
+## API
+
+List published content:
+
+```text
+GET /api/content
+```
+
+Common query params:
+
+- `page`
+- `limit`
+- `search`
+- `category`
+- `difficulty`
+- `type`
+- `featured=true`
+- `sort`
+
+List categories:
+
+```text
+GET /api/content/categories
+```
+
+## Verification
+
+The Playwright suite verifies:
+
+- Public education resources load.
+- A resource detail page can be opened.
+- Dashboard education management controls render for admins.
+
+Next test improvements:
+
+- Exercise automatic search and filter URLs.
+- Verify featured resources render when seeded content has `isFeatured=true`.
+- Add a publish/unpublish dashboard flow in an isolated test database.

docs/PRODUCTION_READINESS.md

@@ -58,3 +58,7 @@ Avoid the session pooler on port `5432` for app runtimes. It can produce `MaxCli
 The `/api/export` endpoint is intentionally protected behind verified admin or healthcare-provider accounts. Exports are sent with `Cache-Control: no-store` and each successful export writes an audit event with the export type, file format, filters, and row count.
 
 Admins can review recent export activity from the reports dashboard Export History panel or the full audit log at `/dashboard/audit`. See `docs/CLINICAL_EXPORTS.md` for the current export workflow and verification coverage.
+
+## Education Readiness
+
+The public `/education` page depends on the content and category APIs. Before production promotion, confirm seeded or managed content exists, `/api/content` returns published resources, and `/api/content/categories` returns category counts. See `docs/EDUCATION_SYSTEM.md` for the current public browser, automatic search, filters, and content-management workflow.

docs/PROJECT_STATUS.md

@@ -41,10 +41,12 @@ Latest local checks:
 - Patient timeline with role-aware clinical edit links.
 - Upload preview/download management for attachments.
 - Education resource publishing controls.
+- Public education browser with automatic search, URL-backed filters, sorting, featured resources, and live result counts.
 - Demo seed data for patients, appointments, records, pregnancies, ANC visits, newborns, immunizations, reports, notifications, audit logs, and long-form education content.
 - Secured clinical export API with verified admin/provider access, no-store download responses, and audit logging.
 - Reports dashboard Clinical Exports panel for patient, appointment, and medical-record downloads.
 - Admin Export History on the reports dashboard for recent audited export activity.
+- Education system documentation covering public browsing, automatic behavior, content management, and API parameters.
 
 ## Best Next Upgrades
 
@@ -61,7 +63,7 @@ Latest local checks:
    Back up Supabase, restore into a rehearsal DB, verify drift, then replace legacy SQLite-era migrations with the generated PostgreSQL baseline.
 
 5. Deepen the E2E tests from smoke coverage into create/update workflows.
-   Current tests verify entry points, rendering, education reading, health, export security, and dashboard export controls. Next add real patient creation, appointment creation, attachment upload, and clinical record submission in an isolated test database.
+   Current tests verify entry points, rendering, education reading, health, export security, dashboard export controls, and dashboard education management presence. Next add automatic education filter checks, real patient creation, appointment creation, attachment upload, and clinical record submission in an isolated test database.
 
 6. Add production observability review.
    Confirm Web Analytics, Speed Insights, logs, health dashboard, upload storage, Redis rate limiting, and email delivery all behave in a preview/prod environment.

docs/UPGRADE_PLAN.md

@@ -27,6 +27,8 @@ Last updated: 2026-05-07
 - Secured `/api/export` behind verified admin/provider access and audit logging.
 - Added Clinical Exports controls to the reports dashboard.
 - Added admin Export History to the reports dashboard.
+- Rebuilt the public education page with automatic search, working category/type/difficulty filters, sorting, featured resources, and stronger empty/error states.
+- Added `docs/EDUCATION_SYSTEM.md`.
 - Confirmed local verification with lint, typecheck, Jest, Playwright, production build, and production audit.
 
 ## Prisma 7 Status
@@ -82,6 +84,7 @@ Current decision:
 - Add automated protected-preview smoke tests using `VERCEL_PROTECTION_BYPASS`.
 - Clean the ESLint warning backlog reported by `npm run lint:all`.
 - Add deeper end-to-end tests for patient creation, appointment creation, uploads, and submitted clinical forms.
+- Add focused education E2E coverage for automatic search, category filters, sorting, featured resources, and publish/unpublish flows.
 - Plan Better Auth migration as a dedicated project.
 - Activate the PostgreSQL baseline only after Supabase backup and restore rehearsal.
 

e2e/public-and-auth.spec.ts

@@ -5,6 +5,11 @@ test.describe('public and auth flows', () => {
   test('education resources load and a resource can be opened', async ({ page }) => {
     await page.goto('/education');
     await expectPageReady(page, /educational resources/i);
+    await expect(page.getByText(/auto-search/i)).toBeVisible();
+
+    await page.getByLabel(/search/i).fill('pregnancy');
+    await expect(page).toHaveURL(/search=pregnancy/);
+    await expect(page.getByText(/filtered by "pregnancy"/i)).toBeVisible();
 
     const response = await page.request.get('/api/content?page=1&limit=1');
     expect(response.ok()).toBeTruthy();

src/app/api/content/route.ts

@@ -1,6 +1,6 @@
 import { auth } from '@/auth';
 import { prisma } from '@/lib/prisma';
-import { AuditAction, ContentType, DifficultyLevel } from '@prisma/client';
+import { AuditAction, ContentType, DifficultyLevel, type Prisma } from '@prisma/client';
 import { writeAuditLog } from '@/lib/audit';
 import { NextResponse } from 'next/server';
 
@@ -64,8 +64,21 @@ export async function GET(req: Request) {
     const difficulty = searchParams.get('difficulty') as DifficultyLevel | null;
     const type = searchParams.get('type') as ContentType | null;
     const isFeatured = searchParams.get('featured') === 'true';
+    const sort = searchParams.get('sort') || 'newest';
 
     const skip = (page - 1) * limit;
+    const orderBy: Prisma.ContentOrderByWithRelationInput[] = (() => {
+      switch (sort) {
+        case 'popular':
+          return [{ viewCount: 'desc' }, { createdAt: 'desc' }];
+        case 'title-asc':
+          return [{ title: 'asc' }];
+        case 'title-desc':
+          return [{ title: 'desc' }];
+        default:
+          return [{ createdAt: 'desc' }];
+      }
+    })();
 
     const where = {
       isPublished: true,
@@ -77,7 +90,7 @@ export async function GET(req: Request) {
         OR: [
           { title: { contains: search } },
           { description: { contains: search } },
-          { tags: { hasSome: [search] } },
+          { tags: { hasSome: search.split(/\s+/).filter(Boolean) } },
         ],
       }),
     };
@@ -93,7 +106,7 @@ export async function GET(req: Request) {
             select: { name: true, slug: true },
           },
         },
-        orderBy: { createdAt: 'desc' },
+        orderBy,
         skip,
         take: limit,
       }),