blog/docs/frontend.md

# Frontend (Nuxt)

## Pages

| Route | File | Behavior |
|---|---|---|
| `/` | `app/pages/index.vue` | Static hero/intro copy plus the single latest article, fetched via `/content/articles` (page 1), shown as a featured block. |
| `/blog` | `app/pages/blog/index.vue` | Paginated archive (`PAGE_SIZE = 12`), grid of `ArticleCard`, prev/next via `?page=`. |
| `/blog/[slug]` | `app/pages/blog/[slug].vue` | Full article: fetches `/content/articles/:slug`, renders the pre-converted `article.html`, SEO meta, canonical URL, Open Graph, JSON-LD `BlogPosting`, breadcrumb to its category. |
| `/category/[slug]` | `app/pages/category/[slug].vue` | Fetches the category by slug, then a paginated, category-filtered article list; 404s if the category doesn't exist. |
| `/come-difendersi-dal-corralito` | `app/pages/come-difendersi-dal-corralito.vue` | Fully static marketing page, no PocketBase data. |

All pages are SSR (`useFetch`/`useSeoMeta`); nothing blog-related is client-only-rendered.

## Server (Nitro) endpoints — the only PocketBase client

`frontend/server/routes/content/` (not `server/api/` — `/api/*` is reserved for PocketBase itself,
see [architecture.md](./architecture.md#path-routing-caddy); Nitro maps `server/routes/**` to the
matching path with no added prefix, unlike `server/api/**`):

| Endpoint | Purpose |
|---|---|
| `GET /content/articles` | Paginated list (`page` query, `PAGE_SIZE=12`), optional `category` slug filter. Queries PocketBase with `ARTICLE_SUMMARY_FIELDS`. Returns `Paginated<ArticleSummary>`. |
| `GET /content/articles/:slug` | One article: queries PocketBase with `ARTICLE_DETAIL_FIELDS` (includes `content` + `authorName`), converts Markdown to HTML, builds the meta description. 400 without a slug, 404 if not found or unpublished. Returns `Article`. |
| `GET /content/categories` | All categories (name + slug only), sorted by name. |
| `GET /content/categories/:slug` | One category by slug. 400/404 as above. |

This is the **single point of contact** with PocketBase (`CLAUDE.md` rule): pages never call
`$fetch` against PocketBase directly, and `NUXT_POCKETBASE_URL` never reaches the client. If you
add a view that needs new data, add the endpoint here (under `/content/*`) and type its return in
`frontend/shared/types/blog.ts` — don't scatter PocketBase calls into components.

`GET /admin` (`frontend/server/routes/admin.get.ts`) is the one other top-level server route: a
redirect to `${runtimeConfig.public.pocketbaseUrl}/_/`, PocketBase's own fixed dashboard path. It
lives in Nitro rather than Caddy so it works the same in dev (no Caddy in that stack) and
production — see [architecture.md](./architecture.md#path-routing-caddy).

## Supporting utilities

- `frontend/server/utils/pocketbase.ts`
  - `pbFetch<T>(path)` — server-only fetch against `runtimeConfig.pocketbaseUrl`; wraps failures
    as a 502 so internal details never leak to the client.
  - `toMediaImage(collection, id, filename, alt)` — builds a PocketBase file URL
    (`/api/files/{collection}/{id}/{filename}`) from a record; returns `null` when there's no
    file.
  - `renderMarkdown(source)` — `marked.parse()`, no sanitization (trusted, admin-only content).
  - `summarise(source, maxLength = 155)` — strips Markdown syntax to build a plain-text meta
    description, word-boundary clipped.
- `frontend/server/utils/queries.ts` — PocketBase query-string builders kept intentionally minimal
  (only the fields each page actually renders): `ARTICLE_SUMMARY_FIELDS`, `ARTICLE_DETAIL_FIELDS`,
  `PAGE_SIZE`, `pagination()`, `pageParam()`, `quote()` (escapes a value for PocketBase's `filter`
  DSL).
- `frontend/app/composables/useMediaUrl.ts` — the only composable; turns a `MediaImage` into an
  absolute browser URL by prefixing `runtimeConfig.public.pocketbaseUrl` unless already absolute.
- `frontend/shared/utils/site.ts` — site constants (`SITE_NAME`, `SITE_EMAIL`, `SOCIAL_LINKS`).
- `frontend/shared/utils/format.ts` — `it-IT` date formatting (`formatDate`, `formatDateTime`,
  `isoDate`).

## Types (`frontend/shared/types/blog.ts`)

```
MediaImage    { url, alt }
Category      { name, slug }
ArticleSummary{ title, slug, publishedAt, cover: MediaImage | null, category: Category | null }
Article       extends ArticleSummary { html, summary, author: string | null }
Paginated<T>  { items: T[], page, pageCount, total }
```

`Article` is the detail shape (adds rendered HTML, meta summary, byline); `ArticleSummary` is what
listing pages use. `MediaImage` carries no width/height — PocketBase file fields don't store
dimensions, and the covers already reserve their aspect ratio via CSS (`aspect-ratio`), so no
layout shift results.

## Layout & shared components

- `app/layouts/default.vue` — the only layout: header (logo, tagline, nav), `<main id="main">`
  slot, footer (contact email, nav, social links), with a skip-link for accessibility.
- `app/components/ArticleCard.vue` — listing-grid card: cover (lazy, omitted if none), category
  kicker, title link, formatted date.
- `app/components/SocialIcon.vue` — inlines SVG brand marks from `simple-icons` at build time
  (`?raw` imports) rather than bundling the whole icon set.

## SEO & accessibility

Every article page ships: unique `<title>`, meta description, canonical URL, Open Graph tags, and
JSON-LD `BlogPosting` structured data, with the article body already present in server-rendered
HTML (no client-only content). Accessibility requirements (focus visibility, labeled inputs,
meaningful alt text, descriptive links, full keyboard navigation) apply across all pages/components
— see `CLAUDE.md`.

## Tests (`tests/`, repo root)

Kept at the repo root, not under `frontend/`, since e2e exercises the frontend *and* PocketBase
together — but the tooling (Vitest/Playwright configs, `node_modules`) still lives in `frontend/`,
the only npm project in the repo; the configs there just point `include`/`testDir` at `../tests/`.

Three layers, all against real code (no mocked PocketBase):

- `tests/unit/` — Vitest, `environment: 'nuxt'` (`frontend/vitest.unit.config.ts`). Pure functions
  in `frontend/server/utils/*` and `frontend/shared/utils/*` (imported directly, not via
  auto-import) plus components and composables via `@nuxt/test-utils/runtime`'s `mountSuspended`.
- `tests/integration/` — Vitest, node environment (`frontend/vitest.integration.config.ts`).
  `@nuxt/test-utils/e2e`'s `setup()` builds and runs the real Nitro server, pointed (via
  `nuxtConfig.runtimeConfig` overrides) at a real ephemeral PocketBase instance from
  `tests/support/pocketbase.ts`. Exercises the actual `/content/*` and `/admin` routes.
- `tests/e2e/` — Playwright (`frontend/playwright.config.ts`), a real browser against the built
  app (`node .output/server/index.mjs`) and another ephemeral PocketBase on a fixed port (needed
  so the Nuxt server's env and Playwright's `globalSetup` can reference each other without an
  async hand-off — see the comments in `playwright.config.ts`/`tests/e2e/global-setup.ts`).

`tests/support/pocketbase.ts` is the shared piece: it downloads the same pinned PocketBase binary
`pocketbase/Dockerfile` uses (cached in `.cache/pocketbase/` at the repo root, gitignored), starts
it against the real `pocketbase/pb_migrations/`, and seeds it from `tests/support/fixtures.ts` —
so integration and e2e tests run against the exact schema/rules that ship to production, not a
hand-maintained approximation of them.