biggus-dickus/docs/superpowers/specs/2026-06-04-frontend-spa-milestone-4-design.md

# Frontend SPA — Milestone 4 (Vocabulary & Authority Management) — Design

**Date:** 2026-06-04
**Status:** Approved (brainstorming) — ready for implementation planning.

## Context

Milestones 1–3 (merged to `main` at `7a8e7ff`) delivered the SPA foundation, object
read/authoring, and the publishing workflow. The app shell's nav has **Vocabularies**
and **Authorities** items rendered as disabled stubs. Milestone 4 enables them: managing
the controlled vocabularies (and their terms) and the authority records that catalogue
fields reference.

Pure frontend — the admin endpoints already exist (built in the backend admin-CRUD
phase): `GET/POST /api/admin/vocabularies`, `GET/POST /api/admin/vocabularies/{id}/terms`,
`GET/POST /api/admin/authorities?kind=`.

Milestone roadmap: M1 foundation → M2 authoring → M3 publish → **M4 vocab/authority
(this)** → M5 search.

## Decisions (settled during brainstorming)

- **One milestone for both surfaces** (vocabularies+terms and authorities), sharing a
  `LabelEditor` and a create-form pattern.
- **Two-pane master–detail layout** (consistent with the Objects inspector): the
  Vocabularies screen is vocab-list-left / terms-right; Authorities is kind-tabs + list.
- **Create + list only.** The backend exposes only create and list for vocabularies,
  terms, and authorities — no update/delete — so M4 is create + list. Editing/deleting
  reference data is a later milestone (needs backend endpoints first).
- **Fixed sv/en `LabelEditor`** (not arbitrary languages), matching the app's sv/en MVP
  scope and M2's `localized_text` field; produces `LabelInput[]` of non-empty langs.
- **EN label required, SV optional** (canonical English), consistent with M2.

## Backend contract (already shipped — verify against `web/src/api/schema.d.ts`)

- `GET /api/admin/vocabularies` → `VocabularyView[]` (`{ id, key }`).
- `POST /api/admin/vocabularies` body `NewVocabularyRequest { key }` → `201 VocabularyView`.
- `GET /api/admin/vocabularies/{id}/terms` → `TermView[]` (`{ id, external_uri?, labels }`).
- `POST /api/admin/vocabularies/{id}/terms` body `NewTermRequest { external_uri?, labels }`
  → `201 CreatedId`.
- `GET /api/admin/authorities?kind=person|organisation|place` → `AuthorityView[]`
  (`{ id, kind, external_uri?, labels }`).
- `POST /api/admin/authorities` body `NewAuthorityRequest { kind, external_uri?, labels }`
  → `201 CreatedId`.
- `LabelInput` / `LabelView` = `{ lang, label }`.

(Existing hooks from M2: `useTerms(vocabularyId)`, `useAuthorities(kind)`.)

## Scope (YAGNI)

**In:** Vocabularies screen (list + create vocabulary; per-vocab terms list + add term);
Authorities screen (kind-tabbed list + create authority); shared `LabelEditor` (sv/en);
4 new hooks; the two nav stubs enabled; client validation; list invalidation on create.

**Out:** update/delete of vocab/term/authority (no backend endpoints — later milestone);
audit of vocab/authority creation (backend follow-up #21); searchable pickers (#27);
search UI (M5); per-language beyond sv/en.

## Architecture

### Routes & navigation

Enable the `Vocabularies` and `Authorities` nav items in `app-shell.tsx` (currently
disabled buttons → active `NavLink`s). Routes under the protected `AppShell`, two-pane
via nested `<Outlet/>` like Objects:

```
/vocabularies            → VocabulariesPage (list + create left; <Outlet/> right)
    index                → "select a vocabulary" prompt
    :id                  → VocabularyTerms (the vocab's terms + add-term form)
/authorities             → redirect to /authorities/person
/authorities/:kind       → AuthoritiesPage (kind tabs + list + create), kind ∈ person|organisation|place
```

`/authorities/:kind` validates the kind param (unknown → redirect to `person`).

### Components / files

```
web/src/vocab/
  vocabularies-page.tsx     two-pane: VocabularyList (+ create) left, <Outlet/> right
  vocabulary-list.tsx       useVocabularies list + NewVocabularyForm
  vocabulary-terms.tsx      (:id) useTerms list + AddTermForm
web/src/authorities/
  authorities-page.tsx      kind tabs + AuthorityList(kind) + NewAuthorityForm(kind)
web/src/components/
  label-editor.tsx          shared sv/en label editor (RHF-controlled), -> LabelInput[]
web/src/api/queries.ts      + useVocabularies, useCreateVocabulary, useAddTerm, useCreateAuthority
web/src/app.tsx             + the routes above
web/src/shell/app-shell.tsx enable the Vocabularies + Authorities nav links
web/src/i18n/{en,sv}.json   + vocab.* / authorities.* keys
```

Keep each page focused; the create forms (`NewVocabularyForm`, `AddTermForm`,
`NewAuthorityForm`) are small and may live in their page files or as siblings — the
shared piece that must be its own unit is `LabelEditor`.

### `LabelEditor`

A controlled editor rendering an **English** input and a **Swedish** input. Given/produces
`LabelInput[]` (`{ lang, label }`). On change it emits the array with only the non-empty
langs (so an empty SV is omitted). Used by `AddTermForm` and `NewAuthorityForm`.
Validation: the EN label is required (the parent form wires `required` on the EN field);
SV optional. (Mirrors M2's `localized_text` handling and the existing detail/edit label
rendering.)

### Data layer (new hooks in `queries.ts`)

- `useVocabularies()` → `GET /api/admin/vocabularies` → `VocabularyView[]`.
- `useCreateVocabulary()` → `POST /api/admin/vocabularies` `{ key }`; invalidate
  `["vocabularies"]`.
- `useAddTerm()` → `POST /api/admin/vocabularies/{id}/terms` `{ external_uri?, labels }`;
  invalidate `["terms", vocabularyId]`.
- `useCreateAuthority()` → `POST /api/admin/authorities` `{ kind, external_uri?, labels }`;
  invalidate `["authorities", kind]`.

(`useTerms`/`useAuthorities` already use keys `["terms", vocabularyId]` /
`["authorities", kind]`; the mutations invalidate those exact keys.)

### Data flow

- **Create vocabulary:** form (`key`) → `useCreateVocabulary` → invalidate list; clear form.
- **Add term:** form (sv/en labels + optional uri) on `/vocabularies/:id` →
  `useAddTerm({ id, labels, external_uri })` → invalidate `["terms", id]`; clear form.
- **Create authority:** form on `/authorities/:kind` (labels + optional uri) →
  `useCreateAuthority({ kind, labels, external_uri })` → invalidate `["authorities", kind]`;
  clear form.

## Error handling

Create failures → a form-level error (reuse `form.rejected`). Lists show loading /
empty / error states (reuse the M1 list-state patterns). Required validation (vocab key;
EN label) blocks submit with inline messages. Unknown authority kind in the route →
redirect to `person`.

## Testing (Vitest + RTL + MSW)

- `LabelEditor` — entering EN+SV produces `[{lang:"en",...},{lang:"sv",...}]`; empty SV
  omitted.
- Vocabularies: list renders; create a vocabulary → POST `{key}` (assert body) → list
  invalidated/refetched shows it; selecting a vocab shows its terms; add a term →
  POST with the labels body (assert) → terms refetch.
- Authorities: kind tabs switch the list (`?kind=`); create an authority for the active
  kind → POST `{kind, labels}` (assert) → list refetch; required EN label blocks submit.
- Nav: the Vocabularies + Authorities nav items are enabled links (not disabled).
- New MSW handlers: `POST /api/admin/vocabularies`, `POST /api/admin/vocabularies/:id/terms`,
  `POST /api/admin/authorities` (the GET handlers + the existing `?kind=` filter handler
  are already present from M2).

## Acceptance criteria (Milestone 4 "done")

1. The Vocabularies and Authorities nav items are enabled and route to their screens.
2. A vocabulary can be created (key) and appears in the list; selecting it shows its
   terms; a term can be added with sv/en labels (+ optional URI) and appears.
3. Authorities can be filtered by kind via tabs; an authority can be created for the
   active kind with sv/en labels and appears in that kind's list.
4. The shared `LabelEditor` produces `LabelInput[]` with only non-empty langs; EN is
   required.
5. Create failures surface a form-level error; lists have loading/empty/error states.
6. Web CI green (typecheck, lint, tests, build, bundle ≤150 KB gz).

## Out of scope / follow-ups

- Edit/delete of vocabularies, terms, authorities — needs backend endpoints first
  (file a backend follow-up when this milestone lands).
- Audit of vocab/term/authority creation (#21).
- Searchable pickers / large-vocabulary handling (#27).
- Arbitrary (non sv/en) label languages.