docs(spec): frontend SPA milestone 4 (vocabulary & authority management) design

Two-pane vocab (list/create + terms/add) + kind-tabbed authorities
(list/create); shared sv/en LabelEditor; create+list only (no backend
edit/delete yet); 4 new hooks; enables the nav stubs; Vitest+RTL+MSW.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

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

@@ -0,0 +1,168 @@
+# 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.